Delete Data
Delete a specific data item from a dataset.
This endpoint removes a specific data item from a dataset while keeping the dataset itself intact. The user must have delete permissions on the dataset to perform this operation.
Path Parameters
- dataset_id (UUID): The unique identifier of the dataset containing the data
- data_id (UUID): The unique identifier of the data item to delete
Response
A deletion receipt (DeleteDataReceiptDTO, camelCase on the wire): status
("success", or "not_found" when neither a Data row nor a graph element
existed for the id — nothing removed, counts 0, still a 200 because deleting
is idempotent), datasetId, dataId (the resolved id), dataRecordFound
(a Data row for the id existed), deletedNodes / deletedEdges (graph
elements removed), dataRemaining (false when an existence check after the
delete no longer finds the Data row — the verified outcome; null when no Data
row existed) and datasetDeleted (always false here).
Changed (SDK-1150): releases up to 1.6.x answered null (no body) on success.
Clients that asserted an empty 200 now receive the receipt; the status key
keeps its historical value.
Error Codes
- 401 Unauthorized: Dataset doesn’t exist or user lacks delete permission
- 500 Internal Server Error: The Data row was still present after the delete
(
DataDeletionIncompleteError; retry), or another error during deletion
Notes
A data_id with no Data row but with graph elements it owns is a custom-graph-
model deletion: those elements are removed and the receipt says
dataRecordFound: false, dataRemaining: null. A data_id that owns
nothing (mistyped, another dataset’s, or already deleted) answers
status: "not_found" with zero counts — check status, not just the HTTP
code, before treating a delete as verified.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Dataset UUID, the id field from GET /api/v1/datasets (not the name)
"b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e"
Data item UUID, from GET /api/v1/datasets/{dataset_id}/data
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
Response
Successful Response
The deletion receipt datasets.delete_data returns.
This is the single definition of the receipt: delete_data builds it and
hands SDK callers its model_dump (snake_case keys), and the REST routes
that return it (DELETE /datasets/{dataset_id}/data/{data_id}, DELETE /delete, DELETE /forget with a data_id) carry the same dict, this
route validating it as its response_model (camelCase on the wire).
status never contradicts the outcome: success when something was
removed (graph elements other data still shares lose only the id's
ownership, so the counts can be 0), not_found when neither a
Data row nor a graph element existed for the id (nothing removed, counts 0; deleting is idempotent,
so this is a 200, and delete_dataset_if_empty is still honoured). A
delete whose Data row is still present afterwards raises
DataDeletionIncompleteError (500) instead of any receipt. So
data_remaining is false (observed by an existence check after the
delete, the verified outcome — read it together with
data_record_found: true) or null (no Data row existed, so there
was nothing to observe).
'success' when something was removed; 'not_found' when neither a Data row nor a graph element existed for the id (nothing removed). A Data row that survives the delete answers 500 instead of a receipt.
success, not_found The dataset the item was deleted from.
The resolved id of the deleted item (differs from the path when a legacy id was given).
A Data row existed for the id. False means only graph elements owned by the id were removed (custom graph model).
Graph nodes removed by this delete. Approximate on the legacy (pre-provenance) graph path, where it also counts the chunk 'contains' edge-vector ids removed with the nodes.
Graph edges removed by this delete. 0 on the legacy (pre-provenance) graph path, which does not track the edges it detaches.
False when an existence check after the delete no longer finds the Data row (the verified outcome; meaningful only with dataRecordFound true). Null when no Data row existed. Never true on a returned receipt: that case fails with 500.
The now-empty dataset was removed as well (only when delete_dataset_if_empty was requested).