> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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_id` that you choose.
* A human-readable `display_name`.
* A `metadata` JSON object for your own structured fields.

All endpoints use your Mosaic API key and are automatically scoped to its organization.

```bash theme={null}
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:

```json theme={null}
{ "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.