---
title: "Patch Document"
method: PATCH
path: "/v1/documents/{document_id}"
tags: ["documents"]
---

# Patch Document

`PATCH /v1/documents/{document_id}`

## Request

- Base URL: `https://api.versionstory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.versionstory.com/v1/documents/{document_id}`
- Auth: HTTP bearer

Rename a document or change its metadata. The answer is the Document.

Send only what changes, {"name"?, "metadata"?}, at least one of them: metadata merges into what is stored, a key sent
replacing that key and a key sent as null removing it.

## Path parameters

- `document_id` string, required: The Document's document_id, a UUID.

## Headers

- `X-Customer-Id` string, nullable: Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide.

## Request body

- DocumentPatchRequest: What a PATCH changes: name, metadata or both.
  - `name` string, nullable: The Document's new name.
  - `metadata` object, nullable: String values by key, merged into what is stored: a key sent is added or replaced, a key sent as null is removed, and a key left out stays.

## Response `200`

Successful Response

- Document: A Document: a named history of versions, each a file, every version after the first with its redline against the version before it.
  - `document_id` string, required: The Document's id.
  - `name` string, nullable: The Document's name: the name it was given, else its first file's.
  - `version_count` integer, required: How many versions it has.
  - `latest_version` VersionReference: A version a response points at: a parent, a Document's latest version, an edit's version. Sent back as it is, it names the version in a request (VersionLocator reads its version_id).
    - `document_id` string, required: The Document the version belongs to.
    - `version_id` string, required: The version's id.
    - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id.
    - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it.
  - `created_at` string, nullable: When the Document was made: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.
  - `updated_at` string, nullable: When the Document last changed: ISO 8601 in UTC, to the second: 2026-10-21T18:22:31Z.
  - `metadata` object: Your own string values by key, stored and returned as they were sent.

## Other responses

- `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal.

---

[API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)