Deleting Content
Remove documents and nodes from your knowledge graph
Deleting Content
Remove content and individual nodes from your knowledge graph.
Delete content and all its associated child nodes (sections, frames, metadata):
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}" \
-H "Authorization: Bearer YOUR_API_KEY"Response:
{
"deletion_type": "full",
"document_id": "doc_ai_research_2024",
"deleted": {
"documents": 1,
"sections": 5,
"frames": 23,
"relationships": null,
"vault_files": 1
},
"preserved": {
"shared_frames": 2,
"shared_frame_ids": ["frame_abc123", "frame_def456"]
},
"cancelled_jobs": [],
"warnings": ["2 frame(s) with external references will be preserved. Use force=true to delete all frames."]
}Note: Frames that are referenced by other documents are automatically preserved when deleting content. This maintains graph connectivity so those frames can still be found via traversal from other documents. Only frames exclusive to the deleted document are removed.
Dry Run Mode
Preview what will be deleted without making changes:
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}?dry_run=true" \
-H "Authorization: Bearer YOUR_API_KEY"Force Deletion
By default, frames that are referenced by other documents are preserved. Use force=true to delete all frames regardless of external references:
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}?force=true" \
-H "Authorization: Bearer YOUR_API_KEY"Warning: Using
force=truemay break graph connectivity if other documents reference the deleted frames. Only use this when you want a complete cleanup.
Job Cancellation
When you delete a document that is still being processed, any running ingestion jobs are automatically cancelled. This saves costs by stopping unnecessary processing.
The response includes information about cancelled jobs:
{
"cancelled_jobs": [
{"job_id": "ingest_abc123_1234567890", "tasks_revoked": 5}
]
}You can also manually cancel jobs via the Jobs API.
Orphan Cleanup
By default, orphaned nodes (nodes with no relationships) are automatically cleaned up after deletion:
# Cleanup enabled (default)
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}?cleanup_orphans=true" \
-H "Authorization: Bearer YOUR_API_KEY"
# Disable cleanup
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}?cleanup_orphans=false" \
-H "Authorization: Bearer YOUR_API_KEY"Orphan cleanup removes nodes that have no relationships and disconnected metadata clusters.
Deleting Individual Nodes
Delete a single node from the graph:
curl -X DELETE "https://api.recurse.dev/node/{node_id}/delete" \
-H "Authorization: Bearer YOUR_API_KEY"Response:
{
"node_id": "frame_claim_123",
"labels": ["Frame", "Claim"],
"deleted": {
"nodes": 1,
"relationships": 3
},
"warnings": []
}Dry Run for Nodes
Preview node deletion:
curl -X DELETE "https://api.recurse.dev/node/{node_id}/delete?dry_run=true" \
-H "Authorization: Bearer YOUR_API_KEY"Restrictions
- Cannot delete authentication/identity nodes (User, Role, APIKey, Permission, Identity)
- Document nodes must be deleted via
/documents/{id}endpoint - Only nodes you own can be deleted
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dry_run | boolean | false | Preview deletion without making changes |
force | boolean | false | Delete ALL frames, including those with external references |
cleanup_orphans | boolean | true | Remove orphaned nodes after deletion |
Examples
Delete Content
curl -X DELETE "https://api.recurse.dev/documents/doc_my_document" \
-H "Authorization: Bearer YOUR_API_KEY"Delete a Specific Frame
curl -X DELETE "https://api.recurse.dev/node/frame_claim_123/delete" \
-H "Authorization: Bearer YOUR_API_KEY"Preview Before Deleting
curl -X DELETE "https://api.recurse.dev/documents/{doc_id}?dry_run=true" \
-H "Authorization: Bearer YOUR_API_KEY"