---
title: "Update a document's caller tags"
method: PATCH
path: "/v1/documents/{id}"
tags: ["Documents"]
---

# Update a document's caller tags

`PATCH /v1/documents/{id}`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/documents/{id}`
- Auth: HTTP bearer

Post-ingest update of the caller tags accepted at upload time (`batch_id` and `metadata`). `metadata` is MERGED over the stored bag — a patch key wins, `null` is a stored value (never a deletion), and the merged bag must satisfy the same caps as at ingest (≤50 keys, key ≤128 chars, string value ≤1024 chars) or the request is rejected with the document unchanged. `batch_id` is three-state: a non-blank string sets it, `null` clears it, and omitting the field leaves it untouched. Note that a byte-identical re-upload does NOT update tags (dedup keeps the canonical document's original tags) — this endpoint is the way to change what an existing document id carries. Pipelines read `batch_id`/`metadata` at run time, so a later run or rerun of the document picks the new tags up.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `batch_id` string, nullable: Grouping key — string sets, null clears, absent untouched.
  - `metadata` object: Flat primitive bag merged over the stored metadata.

## Response `200`

Updated tags. `batch_id`/`metadata` are echoed only when set.

- object
  - `id` string, uuid, required
  - `updated` boolean, required
  - `batch_id` string
  - `metadata` object

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)