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
| Header | Type | Required | Allowed value and meaning |
|---|---|---|---|
Authorization | string | Yes | Bearer <Mosaic API key>. The key's organization must own the store. |
Content-Type | string | Yes | application/json. |
Path parameters
| Parameter | Type | Required | Allowed value and meaning |
|---|---|---|---|
store_id | UUID string | Yes | Mosaic-generated store.id that will own the entry. |
entry_id | string | Yes | Exact 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
| Field | Type | Required | Possible values |
|---|---|---|---|
display_name | string | Yes | Any non-empty label after surrounding whitespace is removed. |
metadata | JSON object | No | Any 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"
}
}| Field | Type | Meaning and possible values |
|---|---|---|
entry | object | The complete entry after creation or replacement. The object always contains every field listed below. |
entry.entry_id | string | Store-scoped ID taken from the {entry_id} URL path. It is created when absent and unchanged when an existing entry is replaced. |
entry.display_name | string | Trimmed non-empty label accepted from the request. |
entry.metadata | JSON object | Metadata 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_at | ISO 8601 string | UTC 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
}| Status | Payload | Possible 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. |