# Rename a category or change its external key

`PATCH https://api.cream-ai.de/api/v1/categories/{id}`

Changes `name` and/or `external_key` (at least one). `external_key: null` removes the key. Moving a category (`parent_id`) is not supported in v1. A key used by another category returns `409 external_key_exists` with `details.category_id`. If another request changed the same field of this category at the same time, the response is `503 service_unavailable` with `Retry-After`; repeat the request.

Scopes: `categories:write`

## Parameters

- `id` (path, required): Id of the category.
- `Idempotency-Key` (header): Optional unique key of this write request (1–128 visible ASCII characters). Retries with the same key return the stored response.

## Request body

- `name` (string): New name.
- `external_key` (nullable string): New external key; null removes it.

## Returns

- 200: The updated category.

## Errors

- 400: Invalid request (invalid_request, invalid_json, invalid_cursor, idempotency_key_required, invalid_idempotency_key, parent_not_found, max_depth_exceeded, narration_too_long, user_not_in_company, template_not_found, category_not_found, feedback_kind_unsupported, upload_not_found).
- 401: Missing, malformed, revoked or expired API key (unauthorized).
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 404: Not found (not_found).
- 409: Conflict (category_exists, external_key_exists, external_key_conflict, category_limit_reached, idempotency_in_progress, version_conflict, previous_version_creating, film_deleted, not_cancellable, file_unavailable, storyboard_not_ready, storyboard_not_current, timeline_outdated, preview_in_progress, preview_not_ready, preview_unsupported, feedback_queue_full, feedback_not_cancellable, feedback_not_retryable, feedback_busy, revision_locked, film_not_ready, film_busy, no_open_comments, comments_not_open, correction_in_progress, upload_quota_exceeded, film_cancelled).
- 413: Request body too large (payload_too_large).
- 415: Request body is not JSON (unsupported_media_type).
- 422: Idempotency-Key reused with a different request (idempotency_mismatch).
- 429: Too many requests (rate_limited).
- 500: Internal error (internal). Quote the request id when you contact support.
- 503: Temporarily unavailable (service_unavailable). Retry later (after Retry-After seconds, if sent).

## Example request

```sh
curl -X PATCH "https://api.cream-ai.de/api/v1/categories/rz3p8w1d6c0b" \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MKT101 Marketing – basics"
  }'
```

## Example response (200)

```json
{
  "object": "category",
  "id": "rz3p8w1d6c0b",
  "name": "MKT101 Marketing – basics",
  "parent_id": "mk7t2q9x4v1n",
  "external_key": "MKT101",
  "children": []
}
```