---
title: "Rename document identifier"
method: PUT
path: "/v2/documents/{documentId}/identifier"
tags: ["Documents v2"]
---

# Rename document identifier

`PUT /v2/documents/{documentId}/identifier`

Rename a published document's identifier. The change is applied live and immediately. Changes do not go through the draft/publish workflow. The former identifier is recorded in the document's rename history to enable automatic redirects. Only published documents can be renamed.

The new identifier must be a valid slug and unused by any other document in the organization. If the new value is identical to the existing value (case-sensitive), the API will return a `200` but not write a history record.

## Path parameters

- `identifier` string, required

## Request body

- object
  - `identifier` string, required — Document identifier slug. Must be 2–48 characters, containing only lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (_). Cannot be a reserved value. If omitted when creating a document, an identifier is auto-generated.

## Response `200`

Identifier renamed successfully.

- object
  - `identifier` string, required — The document identifier after the rename.
  - `name` string, required — Document name.
  - `description` string, nullable, required — Document description.

## Other responses

- `400` — Invalid identifier format — must be 2–48 characters, contain only lowercase letters, digits, hyphens, and underscores, and not be a reserved value.
- `401` — Authentication required.
- `403` — Insufficient permissions to rename the document.
- `404` — Document not found or archived.
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `409` — The target is a draft rather than a published document, or the requested identifier is already in use by another document in the organization (case-insensitive collision).
- `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/versions/6b02f7349d0e/schema)