> ## 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.

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