--- title: Delete collection description: Remove a collection and its derived data. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Delete collection `DELETE /namespaces/{namespace}/collections/{collection}` Remove a collection and its derived data. **Permission:** Cluster key, or a scoped key with write on this collection. [API key types and authentication](/engine/reference/authentication.md). Send Idempotency-Key. Retry the same logical request with the same key and body. Idempotency records remain available for replay for 24 hours. Search and Query return 404 after deletion is accepted. External source objects remain unchanged. Use events webhooks for live status. Read the job to inspect its current state or recover after a missed event. ## Example request ```http DELETE /namespaces/acme/collections/incident-logs HTTP/1.1 Host: engine.example.com Authorization: Bearer Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7 ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. It must be visible to this key. ### `collection` **string · required** Collection name or col_ ID within the namespace. It must be visible to this key. ## Headers ### `Idempotency-Key` **string · required** Unique key for this logical operation. Reuse it only with the same request for retries. Retained for 86,400 seconds. A changed body returns idempotency_conflict. ## Responses ### 202 · Accepted The operation was accepted. The returned job records its progress. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "id": "job_01K6Q6N7D8E9F0G1H2J3K4M5N6", "type": "delete_collection", "status": "running", "namespace": "acme", "collection": "incident-logs", "error": null, "created_at": "2026-10-06T10:00:00Z", "updated_at": "2026-10-06T10:00:00Z" } ``` #### Response fields ##### `collection` **string · optional · nullable** Collection name when this job belongs to a collection. Otherwise omitted. ##### `created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `error` **object · required · nullable** Failure details, or null when no failure is recorded. ###### `error.code` **string · required** Machine-readable reason for the failure. Use this value for program logic and message for display or diagnostics. ###### `error.message` **string · required** Human-readable explanation of the failure. Do not parse this text to decide how to retry. ##### `file_id` **string · optional · nullable** File ID when this job acts on one file. Otherwise omitted. ##### `id` **string · required** Immutable job ID with the job_ prefix. Use it to read the current state. ##### `namespace` **string · optional · nullable** Namespace name when this job belongs to a namespace. ##### `status` **string · required** Current state of the asynchronous work. succeeded, failed, and canceled are terminal states. - `queued`: Accepted and waiting to start. - `running`: Work is in progress. - `succeeded`: Work completed successfully. - `failed`: Work ended with an error. - `canceled`: Work ended after cancellation. ##### `type` **string · required** Kind of work accepted by the API. - `index_file`: Index a new or replacement file. - `delete_file`: Remove a file and clean its derived data. - `reindex_collection`: Rebuild the collection’s derived data. - `delete_collection`: Remove a collection and its derived data. - `delete_namespace`: Remove a namespace and its collections. - `apply_access_rule`: Apply changed governing rules to affected files. ##### `updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ## Errors [Error format and retry guidance](/engine/reference/errors.md). ### 400 · `invalid_request` A field, path, parameter, or conditional request rule is invalid. Correct the request. Unknown fields are rejected. ```json { "error": { "code": "invalid_request", "message": "A field, path, parameter, or conditional request rule is invalid.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 401 · `unauthenticated` The API key is missing, invalid, or revoked. Send an active key in Authorization: Bearer or X-API-Key. ```json { "error": { "code": "unauthenticated", "message": "The API key is missing, invalid, or revoked.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 403 · `forbidden` The key can see the resource but lacks permission for this operation. Use a key with the required action or scope kind. ```json { "error": { "code": "forbidden", "message": "The key can see the resource but lacks permission for this operation.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 404 · `not_found` The resource is absent, deleted, or outside this key’s scope. Check the identifier and the key’s namespace and collection scope. ```json { "error": { "code": "not_found", "message": "The resource is absent, deleted, or outside this key’s scope.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `idempotency_conflict` This idempotency key was already used with a different request body. Reuse the original body for a retry, or choose a new key for a new operation. ```json { "error": { "code": "idempotency_conflict", "message": "This idempotency key was already used with a different request body.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ### 409 · `operation_in_progress` An unfinished operation conflicts with this request. Inspect the existing job and wait for its completion event before retrying. ```json { "error": { "code": "operation_in_progress", "message": "An unfinished operation conflicts with this request.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 503 · `temporarily_unavailable` A dependency, cluster readiness condition, or capacity limit prevents this operation. Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write. ```json { "error": { "code": "temporarily_unavailable", "message": "A dependency, cluster readiness condition, or capacity limit prevents this operation.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 500 · `internal_error` An unexpected server failure prevented this request from completing. Retain x-request-id for investigation. Follow retryable before retrying a write. ```json { "error": { "code": "internal_error", "message": "An unexpected server failure prevented this request from completing.", "request_id": "req_example", "retryable": false, "details": {} } } ``` ## Other request languages ### cURL ```bash curl -sS -X DELETE "$GRAPHON_ENGINE_URL/namespaces/acme/collections/incident-logs" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" \ -H 'Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7' ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs", headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, method="DELETE", ) with urllib.request.urlopen(request) as response: print(response.read().decode()) ``` ### JavaScript ```javascript const response = await fetch(process.env.GRAPHON_ENGINE_URL + "/namespaces/acme/collections/incident-logs", { method: "DELETE", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.