Update collection

Change a collection’s display label, processing flags, or access enforcement.

PATCH/namespaces/{namespace}/collections/{collection}

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

Omitted fields keep their current values. Send display_name: null to clear the label.
Enabling a processing flag can return a reindex job with 202. Turning a flag off disables the Search mode that needs it and does not remove stored content.
Only cluster keys or namespace keys with write may change access_control. Enabling enforcement hides affected content until rule application succeeds. Disabling it keeps the rules.

Request

https://engine.example.com/namespaces/acme/collections/incident-logs

PATCH /namespaces/acme/collections/incident-logs HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "display_name": "Incident logs"
}

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

The update completed without asynchronous work.

{
  "id": "col_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "namespace": "acme",
  "name": "incident-logs",
  "display_name": "Incident logs",
  "status": "ready",
  "access_control": "off",
  "processing": {
    "keyword": true,
    "semantic": true,
    "graph": true
  },
  "index_generation": "gen_example",
  "file_counts": {
    "pending": 0,
    "indexing": 0,
    "ready": 1,
    "failed": 0
  },
  "created_at": "2026-10-06T10:00:00Z",
  "updated_at": "2026-10-06T10:00:00Z"
}

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.

Request body

access_controlstringoptionalaccepts null

Set off or enforced. Only cluster keys and namespace keys with write may change this field. Enabling enforcement hides files until rule application succeeds.

off: Retrieval uses the key’s scope and does not accept principals.
enforced: Retrieval requires principals and applies the collection’s access rules.

display_namestringoptionalaccepts null

Replace the display label. Send null to clear it. Omit this field to keep the current label.

processingobjectoptionalaccepts null

Index features for this collection. Flags omitted on create default to true. Flags omitted on update keep their values. At least one flag must remain enabled.

Responses

200Settings updated

The update completed without asynchronous work.

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.

access_controlstringrequired

Whether Search, Answer, and Research apply access rules. off accepts no principals. enforced requires principals and starts with an empty root reader list.

off: Retrieval uses the key’s scope and does not accept principals.
enforced: Retrieval requires principals and applies the collection’s access rules.

created_atstring (date-time)required

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

display_namestringrequiredaccepts null

Human-readable label. This label does not change the resource name used in URLs.

file_countsobjectrequired

Current number of living files in each processing state.

idstringrequired

Immutable collection ID with the col_ prefix.

index_generationstringrequiredaccepts null

Opaque identifier for the searchable generation. It changes when indexed data changes. Null means that no searchable generation exists.

namestringrequired

URL name. Use 1–63 lowercase letters, digits, underscores, or hyphens. Start with a letter or digit. A name cannot match its resource ID format.

namespacestringrequired

Name of the namespace that contains this collection.

processingobjectrequired

Index features for this collection. Flags omitted on create default to true. Flags omitted on update keep their values. At least one flag must remain enabled.

statusstringrequired

Aggregate readiness of the collection. A ready file permits retrieval. Check file_counts for failures or ongoing processing.

empty: No living files. Search returns no results. Answer returns collection_empty.
indexing: Files are processing and none is ready yet.
ready: At least one file is ready for retrieval.
degraded: At least one file is ready and at least one failed.
failed: Files exist but none is ready. Inspect file errors.
deleting: Deletion is in progress. Retrieval returns not_found.

updated_atstring (date-time)required

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

202Reindex accepted

Enabling a previously disabled processing flag starts a reindex. The response is the job.

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.

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.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

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