Skip to content
Dashboard
API Reference

Create or Replace an Entry ​

Idempotently create or replace one entry.

This page documents its request, success response, and error response fields in full.

PUT is safe to retry. It replaces display_name and metadata for the entry ID in the URL. Each store can contain up to 10,000 entries; replacing an existing entry does not consume another slot.

Request ​

Headers ​

HeaderTypeRequiredAllowed value and meaning
AuthorizationstringYesBearer <Mosaic API key>. The key's organization must own the store.
Content-TypestringYesapplication/json.

Path parameters ​

ParameterTypeRequiredAllowed value and meaning
store_idUUID stringYesMosaic-generated store.id that will own the entry.
entry_idstringYesExact non-empty caller-defined ID to create or replace within the store. URL-encode reserved path characters.

This endpoint has no query parameters.

bash
curl -X PUT \
  "https://api.mosaic.so/shared-stores/11111111-1111-4111-8111-111111111111/entries/0689B" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Jordan Lee",
    "metadata": { "age": 31, "market": "Austin" }
  }'

metadata must be a JSON object no larger than 256 KB.

JSON body ​

FieldTypeRequiredPossible values
display_namestringYesAny non-empty label after surrounding whitespace is removed.
metadataJSON objectNoAny object up to 256 KB. Omitted or null becomes {}. The object may contain any JSON values.

Response ​

200 OK ​

json
{
  "entry": {
    "entry_id": "0689B",
    "display_name": "Jordan Lee",
    "metadata": { "age": 31, "market": "Austin" },
    "created_at": "2026-08-03T20:00:00Z"
  }
}
FieldTypeMeaning and possible values
entryobjectThe complete entry after creation or replacement. The object always contains every field listed below.
entry.entry_idstringStore-scoped ID taken from the {entry_id} URL path. It is created when absent and unchanged when an existing entry is replaced.
entry.display_namestringTrimmed non-empty label accepted from the request.
entry.metadataJSON objectMetadata accepted from the request. Always an object and never null; omitted or null request metadata is returned as {}. May contain any JSON values and is limited to 256 KB.
entry.created_atISO 8601 stringUTC timestamp of initial creation. Replacing an existing entry preserves its original timestamp.

Error responses ​

409 Conflict — store limit ​

json
{
  "error": "A shared store may have at most 10000 entries",
  "code": "shared_store_entry_limit_reached",
  "limit": 10000
}
StatusPayloadPossible value
400 Bad Request{ "error": "entryId and display_name are required" }The path entry ID or display_name is empty.
400 Bad Request{ "detail": "metadata must be a JSON object" }metadata is an array, string, number, or boolean.
401 Unauthorized{ "detail": string }detail is exactly Authorization header must start with Bearer, invalid_api_key, or API key must be associated with an organization.
403 Forbidden{ "detail": "api_access_required" }API access is unavailable for the organization.
404 Not Found{ "error": "Shared store not found" }The store does not exist or belongs to another organization.
409 Conflict{ "error": string, "code": "shared_store_entry_limit_reached", "limit": 10000 }Creating this ID would exceed 10,000 entries. Replacing an existing ID remains allowed.
413 Payload Too Large{ "detail": "metadata must be 256 KB or smaller" }UTF-8 encoded metadata exceeds 256,000 bytes.
500 Internal Server Error{ "error": "Failed to put shared store entry" }The entry could not be written.