update

Update

Update data in a dataset.

This endpoint updates existing documents in a specified dataset by providing the data_id of the existing document to update and the new document with the changes as the data. The document is updated, analyzed, and the changes are integrated into the knowledge graph.

Request Parameters

data_id (UUID, required, query): UUID of the existing document to update (returned by GET /api/v1/datasets/{dataset_id}/data)
dataset_id (UUID, required, query): UUID of the dataset containing the document to update
data (List[UploadFile]): New version of the document that replaces the existing one.
node_set (Optional[List[str]]): List of node identifiers used to organize and filter data points in the knowledge graph. Not an access-control mechanism.
chunk_level_diff (bool, query, default true): Replace only the chunks affected by the edit instead of re-ingesting the whole document.

Response

One body on every path (UpdateResult), a superset of the chunk-level summary returned before:

status: "incremental" (chunks replaced), "unchanged" (no content change), "full_rebuild" (memory dropped and rebuilt from the new content) or "failed" (the rebuild’s cognify run errored; error says why, and the call can be retried).
regions, deleted_chunks, added_chunks, reused_chunks, redated_chunks, kept_chunks, reindexed_chunks, total_chunks: the chunk-level counters; null on a rebuild, which has no diff.
data_id, dataset_id: the document, the handle to retry with.
duration_seconds: wall-clock time of the update.
pipeline_run_id: the run to inspect; null for a no-op.
fallback: set on every rebuild; its reason names why the chunk-level path did not run (disabled, unsupported_metadata, custom_extraction_config, per_call_db_config, unsupported_backend, unsupported_chunker, no_baseline, chunks_not_tiling, unreadable_text) and detail says it in a sentence.
error: error_class and message when status is "failed".

Error Codes

422 Unprocessable Entity: data_id or dataset_id missing or not a valid UUID
403 Forbidden: User lacks write permission on the dataset
404 Not Found: data_id resolves to no document in the dataset
500 Internal Server Error: the rebuild’s cognify run errored (body is the UpdateResult with status "failed") or an unexpected error occurred

Notes

Chunk-level updates keep unaffected chunks, their entities, and their summaries untouched; only the edited region is re-extracted.

PATCH

api

update

Update

curl --request PATCH \
  --url https://{tenant}.aws.cognee.ai/api/v1/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form data=@example-file

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/update"

files = { "data": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.patch(url, files=files, headers=headers)

print(response.text)

{
  "status": "incremental",
  "data_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "duration_seconds": 123,
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "redated_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123,
  "total_chunks": 123,
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fallback": {
    "reason": "disabled",
    "detail": "<string>"
  },
  "error": {
    "error_class": "<string>",
    "message": "<string>"
  }
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "status": "incremental",
  "data_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "duration_seconds": 123,
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "redated_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123,
  "total_chunks": 123,
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fallback": {
    "reason": "disabled",
    "detail": "<string>"
  },
  "error": {
    "error_class": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

data_id

string<uuid>

required

UUID of the existing document to update (returned by GET /api/v1/datasets/{dataset_id}/data).

Example:

"9c4e4a4b-2b1a-4f6e-9d3a-1c2b3d4e5f6a"

dataset_id

string<uuid>

required

UUID of the dataset containing the document to update.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

chunk_level_diff

boolean

default:true

Diff the new content against the stored text and re-ingest only the affected chunks. Falls back to the full rebuild (memory dropped, row refreshed) when chunk-level preconditions are not met.

Body

multipart/form-data

data

file[]

required

New version of the document that replaces the existing one. With chunk_level_diff enabled (default) only the chunks affected by the edit are replaced; otherwise the document is deleted and re-ingested.

node_set

string[] | null

Node identifiers used to organize and filter data points in the graph.

Example:

["user_memories"]

Response

Successful Response

Per-document outcome of update().

status says what happened: the chunk-level path replaced chunks (incremental) or found nothing to change (unchanged), the whole document was rebuilt (full_rebuild), or the rebuild's cognify run errored (failed, with error naming the cause so the call can be retried). A rebuild always carries fallback, naming why the chunk-level path did not run or that the caller switched it off, and duration_seconds makes a slow update visible next to its reason.

The chunk counters are work done by the chunk-level path — added can exceed the net change when a re-cut chunk with unchanged content is re-extracted in place — and total_chunks is the count after the update. redated_chunks are kept chunks whose text did not change but whose date context did (an edit upstream changed the year a year-less date inherits), so they were re-extracted at their final position under their own id; they are included in added_chunks and excluded from reindexed_chunks, which counts only kept chunks renumbered in place. The counters are None on a rebuild, which has no diff. The document keeps its data_id on every path.

status

enum<string>

required

Available options:

incremental,

unchanged,

full_rebuild,

failed

data_id

string<uuid>

required

dataset_id

string<uuid>

required

duration_seconds

number

required

regions

integer | null

deleted_chunks

integer | null

added_chunks

integer | null

reused_chunks

integer | null

redated_chunks

integer | null

kept_chunks

integer | null

reindexed_chunks

integer | null

total_chunks

integer | null

pipeline_run_id

string<uuid> | null

fallback

Fallback · object | null

Why the full rebuild ran instead of the chunk-level update.

Show child attributes

error

UpdateError · object | null

Why the rebuild's cognify run failed.

Show child attributes

⌘I

Update

curl --request PATCH \
  --url https://{tenant}.aws.cognee.ai/api/v1/update \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form data=@example-file

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/update"

files = { "data": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.patch(url, files=files, headers=headers)

print(response.text)

{
  "status": "incremental",
  "data_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "duration_seconds": 123,
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "redated_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123,
  "total_chunks": 123,
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fallback": {
    "reason": "disabled",
    "detail": "<string>"
  },
  "error": {
    "error_class": "<string>",
    "message": "<string>"
  }
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "status": "incremental",
  "data_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "duration_seconds": 123,
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "redated_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123,
  "total_chunks": 123,
  "pipeline_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fallback": {
    "reason": "disabled",
    "detail": "<string>"
  },
  "error": {
    "error_class": "<string>",
    "message": "<string>"
  }
}