---
title: "Update an item"
method: PATCH
path: "/cms/items/{itemId}"
tags: ["CMS items"]
---

# Update an item

`PATCH /cms/items/{itemId}`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/cms/items/{itemId}`
- Auth: HTTP bearer

Patches an item; omitted fields are left untouched. Keys in `data` are merged into the existing values and validated the same way as on create, while each key provided in `references`, `images`, or `files` replaces that field’s value wholesale — pass `null` (or `[]` for multi-valued fields) to clear an optional field. `slug` renames the item’s slug; slug and unique-field collisions fail with a conflict. Pass `position: "first"` or `"last"`, or `"before"` / `"after"` together with `anchorItemId`, to move the item within the collection’s manual order — the default sort for item lists.

## Path parameters

- `itemId` string, required

## Request body

- object
  - `slug` string: New slug for the item — a rename. Omit to keep the current slug. Must be unique among the collection’s active items.
  - `data` object
  - `references` object
  - `images` object
  - `files` object
  - `position` 'before' | 'after' | 'first' | 'last': Moves the item within the collection’s manual order — the default sort for item lists. Omit to leave the order unchanged. `"before"` / `"after"` require `anchorItemId`.
  - `anchorItemId` string: Sibling item to move against when `position` is `"before"` or `"after"`.

## Response `200`

Identity and ordering key of the updated item. Read the full item back with the get-item endpoint.

- object
  - `id` string, required: Id of the updated item.
  - `slug` string, required: Slug of the item after the update.
  - `position` string, required: The item’s fractional ordering key after the update; changes when `position` is used. The default list order sorts by this value.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `409`: The request conflicts with the current state of the resource.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)