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

# Update an Entry

> Change an entry ID, display name, or metadata.

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

## 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` containing the current entry.                                                           |
| `entry_id` | string      | Yes      | Exact current store-scoped entry ID. URL-encode reserved path characters. The JSON body's `entry_id` may rename it. |

This endpoint has no query parameters.

```bash theme={null}
curl -X PATCH \
  "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 '{
    "entry_id": "0689B",
    "display_name": "Jordan Lee",
    "metadata": { "age": 32, "market": "Austin" }
  }'
```

`entry_id` and `display_name` are required. Omit `metadata` to preserve its current value.

### JSON body

| Field          | Type        | Required | Possible values                                                                                     |
| -------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------- |
| `entry_id`     | string      | Yes      | Any non-empty ID. May equal the ID in the URL or rename it to an unused ID in the same store.       |
| `display_name` | string      | Yes      | Any non-empty label after surrounding whitespace is removed.                                        |
| `metadata`     | JSON object | No       | Any object up to 256 KB. Omit to preserve the existing object; send `null` to replace it with `{}`. |

## Response

### `200 OK`

```json theme={null}
{
  "entry": {
    "entry_id": "0689B",
    "display_name": "Jordan Lee",
    "metadata": { "age": 32, "market": "Austin" },
    "created_at": "2026-08-03T20:00:00Z"
  }
}
```

| Field                | Type            | Meaning and possible values                                                                                                                                                                        |
| -------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entry`              | object          | The complete entry after the update. The object always contains every field listed below.                                                                                                          |
| `entry.entry_id`     | string          | New trimmed store-scoped ID accepted from the request. It may remain unchanged or be renamed to an unused ID.                                                                                      |
| `entry.display_name` | string          | New trimmed non-empty label accepted from the request.                                                                                                                                             |
| `entry.metadata`     | JSON object     | Resulting metadata object. Omission preserves the previous object; request `null` produces `{}`. The response field itself is never `null`, may contain any JSON values, and is limited to 256 KB. |
| `entry.created_at`   | ISO 8601 string | UTC timestamp of initial creation. Updating or renaming the entry preserves it.                                                                                                                    |

## Error responses

| Status                      | Payload                                                       | Possible value                                                                                                                              |
| --------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | `{ "error": "entry_id and display_name are required" }`       | A required 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.                                                                                |
| `404 Not Found`             | `{ "error": "Shared store entry not found" }`                 | The current entry ID does not exist.                                                                                                        |
| `409 Conflict`              | `{ "error": "Entry ID already exists in this shared store" }` | The requested new ID is already in use.                                                                                                     |
| `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 rename shared store entry" }`          | The entry could not be updated.                                                                                                             |