---
title: "Update document"
method: PATCH
path: "/v1/default/banks/{bank_id}/documents/{document_id}"
tags: ["Documents"]
---

# Update document

`PATCH /v1/default/banks/{bank_id}/documents/{document_id}`

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/documents/{document_id}`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/documents/:document_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update mutable fields on a document without re-processing its content.

**Tags** (`tags`): The array REPLACES the document's tags, it is not merged into them — send the complete set you want the document to end up with, and any tag you leave out is dropped. An empty array (`[]`) therefore clears every tag.

**Partial tag change** (`add_tags`, `remove_tags`): adds or removes only the listed tags and keeps the rest, e.g. `{"add_tags": ["team-c"], "remove_tags": ["team-a"]}`. Removals apply first. Cannot be combined with `tags` (422). A request with none of `tags`, `add_tags`, `remove_tags` or `observation_scopes` is rejected (422).

The new tags are propagated to all associated memory units.

**Observation scopes** (`observation_scopes`): Replaces how the document's memories are scoped during consolidation, with the same values retain accepts. Use it to move a bank whose documents were retained under per-session tags to `shared` without re-extracting anything. It is also what a later reprocess of the document retains with.

A memory is re-consolidated only when the change moves the observation scopes it resolves to: its observations are deleted and it is queued again, along with co-source memories from other documents that shared those observations. A change that resolves to the same scopes (a tag change under `shared`, `combined` over one tag vs `[[that tag]]`, re-sending the current values) keeps every observation and queues nothing.

## Path parameters

- `bank_id` string, required
- `document_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- UpdateDocumentRequest: Request model for updating a document's mutable fields.
  - `tags` string[], nullable: The complete new set of tags for the document and its memory units — this REPLACES the existing tags rather than adding to them, so omitting a tag drops it and `[]` clears them all. Triggers observation invalidation and re-consolidation. To change only some tags, use `add_tags` / `remove_tags` instead.
  - `add_tags` string[], nullable: Tags to add to the document, keeping the ones it has. Cannot be combined with `tags`.
  - `remove_tags` string[], nullable: Tags to remove from the document, keeping the rest (applied before `add_tags`). Cannot be combined with `tags`. Tags a memory carries from an entity label group with `tag: true` stay on that memory.
  - `observation_scopes` union: New observation scoping for the document's memories, with the same values retain accepts (send 'combined' to scope by each memory's full tag set). Use it to move memories retained under one scoping to another — e.g. per-session documents to 'shared' — without re-extracting them. Memories whose resolved scopes change lose their observations and are re-consolidated; the rest keep theirs. Also becomes the scoping a later reprocess of the document uses.
    - 'per_tag' | 'combined' | 'all_combinations' | 'shared'
    - array[]
      - string[]

## Response `200`

Successful Response

- UpdateDocumentResponse: Response model for update document endpoint.
  - `success` boolean

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-07** `45e711cd0897`: 3 info
  - added the new optional request property `add_tags`
  - added the new optional request property `observation_scopes`
  - added the new optional request property `remove_tags`
- **2026-10-04** `4fda98b75f63`: 1 warning
  - removed the optional property `detail/items/url` from the response with the `422` status
- **2026-05-15** `0d08f271b9db`: 3 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
  - added the optional property `detail/items/url` to the response with the `422` status

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/documents/:document_id/patch.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/45e711cd0897?raw)