> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 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**, **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. ## OpenAPI ````yaml /cognee_openapi_spec.json patch /api/v1/update openapi: 3.1.0 info: title: Cognee API description: Cognee API with Bearer token and Cookie auth version: 1.0.0 servers: - url: https://{tenant}.aws.cognee.ai description: 'Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard' variables: tenant: default: your-tenant description: Your tenant name, shown in the Cognee Cloud dashboard - url: http://localhost:8000 description: 'Self-hosted: a locally running cognee server' security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: activity description: >- Activity endpoints for inspecting pipeline runs, traced spans, tenant users, agents, and dataset exports. - name: add description: Data ingestion endpoints for adding text, files, and structured data. - name: agent connections description: >- Endpoints for registering, unregistering, and inspecting agent connections to the instance. - name: agent management description: Endpoints for creating, listing, retrieving, and deleting agents. - name: auth description: >- Authentication endpoints for user registration, login, and token management. - name: checks description: >- Diagnostic endpoint for validating a Cognee Cloud API key supplied in the X-Api-Key header. - name: cognify description: >- Knowledge processing endpoints to transform raw data into knowledge graphs. - name: configuration description: >- Endpoints for storing, retrieving, and listing a user's saved configurations. - name: datasets description: Dataset management endpoints for listing, creating, and deleting datasets. - name: delete description: Data deletion endpoints (deprecated — use datasets endpoints instead). - name: forget description: Endpoint for removing data from the knowledge graph. - name: health description: Liveness, readiness, and component health checks. - name: improve description: Endpoint for enriching and improving an existing knowledge graph. - name: integrations description: >- Endpoints for connecting, provisioning, and disconnecting OAuth providers and plugins. - name: llm description: >- LLM-backed endpoints for inferring graph schemas and generating custom extraction prompts. - name: memify description: >- Endpoint for running enrichment pipelines over existing graphs or supplied data. - name: ontologies description: >- Endpoints for uploading, listing, and deleting ontology files used during cognify. - name: permissions description: Permission management for multi-user access control. - name: recall description: >- Endpoints for querying the knowledge graph and reviewing past recall history. - name: remember description: >- Endpoints for ingesting data into the knowledge graph and storing session memory entries. - name: responses description: Response generation endpoints using the knowledge graph. - name: schema description: >- Schema inspection endpoints for a dataset's derived schema inventory and the caller-wide memory provenance graph. - name: search description: Search endpoints for querying the knowledge graph. - name: sessions description: >- Endpoints for listing sessions and reporting usage, cost, and token statistics. - name: settings description: Configuration endpoints for managing Cognee settings. - name: skills description: >- Skill management endpoints for ingesting, listing, retrieving, and deleting dataset skills, plus read-only retrieval of improvement proposals. - name: slack description: >- Endpoints for listing workspace channels, setting channel allowlists, and linking Slack accounts. - name: sync description: Endpoints for syncing local data to Cognee Cloud and checking sync status. - name: update description: Endpoint for updating existing data in a dataset. - name: users description: User management endpoints. - name: validate description: >- Diagnostic endpoint for checking consistency between a dataset's graph and vector stores. - name: visualize description: Graph visualization endpoints. paths: /api/v1/update: patch: tags: - update summary: Update description: >- 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 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**, **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. operationId: update_api_v1_update_patch parameters: - name: data_id in: query required: true schema: type: string format: uuid description: >- UUID of the existing document to update (returned by GET /api/v1/datasets/\{dataset_id\}/data). examples: - 9c4e4a4b-2b1a-4f6e-9d3a-1c2b3d4e5f6a title: Data Id description: >- UUID of the existing document to update (returned by GET /api/v1/datasets/\{dataset_id\}/data). - name: dataset_id in: query required: true schema: type: string format: uuid description: UUID of the dataset containing the document to update. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 title: Dataset Id description: UUID of the dataset containing the document to update. - name: chunk_level_diff in: query required: false schema: type: boolean description: >- 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. default: true title: Chunk Level Diff description: >- 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. requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_update_api_v1_update_patch' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UpdateResult' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' '500': description: >- The rebuild's cognify run errored (an UpdateResult with status "failed", naming the error) or an unexpected error occurred. content: application/json: schema: anyOf: - $ref: '#/components/schemas/UpdateResult' - $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' title: Response 500 Update Api V1 Update Patch security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: Body_update_api_v1_update_patch: properties: data: items: type: string format: binary type: array title: Data description: >- 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: anyOf: - items: type: string type: array - type: 'null' title: Node Set description: Node identifiers for graph organization and access control. default: - '' examples: - - user_memories type: object required: - data title: Body_update_api_v1_update_patch UpdateResult: properties: status: type: string enum: - incremental - unchanged - full_rebuild - failed title: Status regions: anyOf: - type: integer - type: 'null' title: Regions deleted_chunks: anyOf: - type: integer - type: 'null' title: Deleted Chunks added_chunks: anyOf: - type: integer - type: 'null' title: Added Chunks reused_chunks: anyOf: - type: integer - type: 'null' title: Reused Chunks kept_chunks: anyOf: - type: integer - type: 'null' title: Kept Chunks reindexed_chunks: anyOf: - type: integer - type: 'null' title: Reindexed Chunks total_chunks: anyOf: - type: integer - type: 'null' title: Total Chunks data_id: type: string format: uuid title: Data Id dataset_id: type: string format: uuid title: Dataset Id duration_seconds: type: number title: Duration Seconds pipeline_run_id: anyOf: - type: string format: uuid - type: 'null' title: Pipeline Run Id fallback: anyOf: - $ref: '#/components/schemas/Fallback' - type: 'null' error: anyOf: - $ref: '#/components/schemas/UpdateError' - type: 'null' type: object required: - status - data_id - dataset_id - duration_seconds title: UpdateResult description: >- 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. They are ``None`` on a rebuild, which has no diff. The document keeps its ``data_id`` on every path. cognee__api__DTO__ErrorResponse: properties: error: type: string title: Error detail: anyOf: - type: string - type: 'null' title: Detail type: object required: - error title: ErrorResponse description: >- Error body returned by routers that answer 4xx/5xx themselves. ``error`` is the human-readable message. Errors raised as ``CogneeApiError`` are rendered instead by the app-level handler in ``cognee/api/client.py`` as ``{"detail": " []"}`` plus ``"remediation"`` when a fix is known. Fallback: properties: reason: $ref: '#/components/schemas/RefusalReason' detail: type: string title: Detail type: object required: - reason - detail title: Fallback description: Why the full rebuild ran instead of the chunk-level update. UpdateError: properties: error_class: anyOf: - type: string - type: 'null' title: Error Class message: anyOf: - type: string - type: 'null' title: Message type: object title: UpdateError description: Why the rebuild's cognify run failed. RefusalReason: type: string enum: - disabled - custom_extraction_config - per_call_db_config - unsupported_backend - unsupported_chunker - unsupported_metadata - no_baseline - chunks_not_tiling - unreadable_text title: RefusalReason description: >- Why a chunk-level update fell back to the full flow. Every refusal used to surface as one free-text message and one log line, so a permanent misconfiguration (an incompatible chunker, an unsupported backend) looked exactly like a first ingestion. The reason is logged as a structured field and returned in ``UpdateResult.fallback`` so they are separable. The first three come from ``update()`` before this engine is consulted; the rest are this engine's own refusals. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````