Graphon Engine

Delete collection

Remove a collection and its derived data.

DELETE/namespaces/{namespace}/collections/{collection}

PermissionCluster key, or a scoped key with write on this collection. Key scopes and actions.

  • Send Idempotency-Key. Retry the same logical request with the same key and body. Idempotency records remain available for replay for 24 hours.
  • Search, Answer, and Research 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.

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

Headers

Idempotency-Keystringrequired

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

202Accepted

The operation was accepted. The returned job records its progress.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

collectionstringoptionalaccepts null

Collection name when this job belongs to a collection. Otherwise omitted.

created_atstring (date-time)required

Time the resource was created, as an ISO 8601 UTC timestamp.

errorobjectrequiredaccepts null

Failure details, or null when no failure is recorded.

file_idstringoptionalaccepts null

File ID when this job acts on one file. Otherwise omitted.

idstringrequired

Immutable job ID with the job_ prefix. Use it to read the current state.

namespacestringoptionalaccepts null

Namespace name when this job belongs to a namespace.

statusstringrequired

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.
typestringrequired

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.
reindex_metadata
Rebuild the metadata index after a change of the metadata fields.
updated_atstring (date-time)required

Time the resource last changed, as an ISO 8601 UTC timestamp.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409idempotency_conflict

This idempotency key was already used with a different request body.

What to do: Reuse the original body for a retry, or choose a new key for a new operation.

409operation_in_progress

An unfinished operation conflicts with this request.

What to do: Inspect the existing job and wait for its completion event before retrying.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?
View as Markdown