Update a document

Renames, moves or replaces a document's content.

PATCH /v1/documents/:id

Permission

The key must be granted docs.documents.write

A key without it gets 403 insufficient_scope, with the missing permission named in details.

Anyone with the document open is told, so a title changed through this API appears in their tab without a reload.

Path parameters

Field	Type	Description
`id` required	string	The document to change.

Request body

Send what changes; omitted fields are left alone. Send one of the two.

Field	Type	Description
`title`	string
`metadata`	object	Replaces the stored object rather than merging into it.

Request

curl https://api.veruapis.com/v1/documents/:id \
  -X PATCH \
  -H "Authorization: Bearer vak_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q3 plan (final)" }'

Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.

Response

Field	Type	Description
`id`	string
`type`	string	`documentspreadsheet`
`title`	string
`state`	string	`activetrashed`
`owner_id`	string	The workspace user who owns it, which is not necessarily the key's owner.
`folder_id`	string	Empty for a document in the root.
`metadata`	object	Whatever you stored on it.
`created_at`	RFC 3339
`updated_at`	RFC 3339

{
  "data": { "id": "0192a1c2-6f3e-7a41-b8d2-5e9f0c3a7b41", "type": "spreadsheet", "title": "Q3 plan (final)", "updated_at": "2026-09-10T09:05:00Z" },
  "meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}

Worth knowing

Anyone with the document open sees the new title without reloading. metadata is replaced wholesale rather than merged, so send the whole object.

Errors

Every failure uses the same shape, with a stable string code you can branch on. See the error reference.

PATCH `/v1/documents/:id`

Your API key Used once, never stored.

id

title