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 for graph organization and access control. Used for grouping related data points in the knowledge graph.
chunk_level_diff (bool, query, default true): Replace only the chunks affected by the edit instead of re-ingesting the whole document.

Response

With chunk_level_diff, a summary of the incremental operation (same keys for either status): {"status": "incremental" | "unchanged", "regions": n, "deleted_chunks": n, "added_chunks": n, "reused_chunks": n, "kept_chunks": n, "reindexed_chunks": n}. When the full flow runs (chunk_level_diff disabled, or its preconditions not met), pipeline run information for the delete + re-add + cognify operation.

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
500 Internal Server Error: Pipeline run errored or an unexpected error occurred during the update

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=<string>' \
  --form data.items='@example-file'

import requests

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

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

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

print(response.text)

{
  "status": "incremental",
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123
}

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

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

{
  "error": "<string>",
  "detail": "<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 delete + re-add + cognify flow 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 for graph organization and access control.

Example:

["user_memories"]

Response

Successful Response

IncrementalUpdateResponse
Response Update Api V1 Update Patch

status

enum<string>

required

Available options:

incremental,

unchanged

regions

integer

required

deleted_chunks

integer

required

added_chunks

integer

required

reused_chunks

integer

required

kept_chunks

integer

required

reindexed_chunks

integer

required

⌘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=<string>' \
  --form data.items='@example-file'

import requests

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

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

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

print(response.text)

{
  "status": "incremental",
  "regions": 123,
  "deleted_chunks": 123,
  "added_chunks": 123,
  "reused_chunks": 123,
  "kept_chunks": 123,
  "reindexed_chunks": 123
}

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

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

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