Shared Stores
Store reusable organization data and keep it synchronized through the API.
Shared stores are organization-scoped collections of reusable records. Certain Mosaic tiles can use these records when processing content.
Each entry has:
- A stable
entry_idthat you choose. - A human-readable
display_name. - A
metadataJSON object for your own structured fields.
All endpoints use your Mosaic API key and are automatically scoped to its organization.
curl "https://api.mosaic.so/shared-stores" \
-H "Authorization: Bearer mk_your_api_key"Limits
| Resource | Limit |
|---|---|
| Shared stores per organization | 10 |
| Entries per shared store | 10,000 |
| Entries per bulk request | 5,000 |
| Metadata per entry | 256 KB |
Creating a resource beyond a store or entry limit returns 409 Conflict with a stable error code and the applicable limit.
IDs
Mosaic generates the UUID returned as store.id. Use that UUID as {store_id} in store and entry endpoint paths.
You provide each entry's entry_id. Entry IDs must be unique within their store and remain the lookup key for API updates.
Data types
Store object
| Field | Type | Possible values |
|---|---|---|
id | UUID string | Mosaic-generated store ID. |
name | string | Any non-empty display name after surrounding whitespace is removed. |
source_type | string | manual by default, or another non-empty caller-supplied source label. This is not an enum. |
created_at | ISO 8601 string | UTC creation timestamp. |
updated_at | ISO 8601 string | UTC last-update timestamp. |
Entry object
| Field | Type | Possible values |
|---|---|---|
entry_id | string | Any non-empty, store-scoped ID supplied by you. URL-encode it when used in a path. |
display_name | string | Any non-empty human-readable label after surrounding whitespace is removed. |
metadata | JSON object | {} or an object up to 256 KB. Keys are strings; values may be any JSON value, including nested objects, arrays, strings, numbers, booleans, and null. The field itself is never null. |
created_at | ISO 8601 string | UTC creation timestamp. Replacing an entry preserves its original creation timestamp. |
Common error responses
Authentication errors use a detail field:
{ "detail": "invalid_api_key" }| Status | detail value | Meaning |
|---|---|---|
401 Unauthorized | Authorization header must start with Bearer | The header is missing or does not use Bearer. |
401 Unauthorized | invalid_api_key | The key is malformed, unknown, or revoked. |
401 Unauthorized | API key must be associated with an organization | The key has no organization scope. |
403 Forbidden | api_access_required | The organization does not have API access. |
Endpoint validation and operational errors use the payloads documented on each endpoint page. A 500 Internal Server Error has an error string describing the failed operation; clients should treat any 500 as retryable only according to their own retry policy.
Endpoints
Use the endpoint pages in the left navigation for request bodies, responses, and errors.