---
title: "Update document"
method: PATCH
path: "/v1/documents/{documentId}"
tags: ["Documents"]
deprecated: true
---

# Update document

`PATCH /v1/documents/{documentId}`

> **Deprecated.**

<Warning>
  **Deprecated** — Removal scheduled for **July 31, 2026**. Use the [Documents v2 API](/api/documents-v2/create-document) instead.
</Warning>

Update the name, description, and/or identifier of a document. **Note**: At least one of `name`, `description`, or `identifier` must be provided or the API will return a `Bad Request` error.

Renaming a document follows the app's draft/publish workflow:

| Document Type | Behavior |
|---------------|----------|
| **Draft** | Renamed directly |
| **Published (no existing draft)** | Creates draft > Renames draft > Publishes draft |
| **Published (existing draft, `clearExistingDraft: true`)** | Discards existing draft > Creates new draft > Renames > Publishes |
| **Published (existing draft, `clearExistingDraft` not set)** | Returns `409 Conflict` |

## Path parameters

- `documentId` string, required

## Request body

- object
  - `name` string — New name for the document.
  - `description` string — Updated description of the document. Set as `null` to clear the description.
  - `clearExistingDraft` boolean — If `true`, discards any existing draft before renaming. **Note**: This parameter is required when a draft exists for the document.
  - `identifier` string — New identifier for the document. Renaming the identifier works with published documents and maintains old URLs via automatic redirects. When you change a document's identifier: - Both the workbook and document identifiers are updated in one transaction - A `DocumentIdentifierHistory` entry is created so requests to the old identifier automatically redirect to the new one - Dashboard and document history entries are updated **Format requirements:** - Must match the pattern: lowercase letters, numbers, hyphens, and underscores only - Cannot start or end with a hyphen or underscore - Must be unique across all documents in your organization **Common use case:** Migrating content between environments (e.g., staging → production) while maintaining specific identifiers.

## Response `200`

Document renamed successfully

- object
  - `identifier` string — The document identifier
  - `name` string — The new document name

## Other responses

- `400` — Bad Request. Possible causes: - Request body must have `name`, `description`, or `identifier` - Name exceeds 255 characters - Description exceeds 1024 characters - Identifier format is invalid (must be lowercase letters, numbers, hyphens, and underscores; cannot start/end with hyphen or underscore) - Identifier is already in use by another document - Draft already exists - set clearExistingDraft to true to discard it and proceed
- `403` — User has insufficient permissions to update document
- `404` — Document not found
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `409` — Conflict. Published document has an existing draft and `clearExistingDraft` is not set to `true`.
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)