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
Path Parameters
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).