Create collection

Create a collection that holds files and one searchable graph.

POST/namespaces/{namespace}/collections

PermissionCluster key, or a namespace key with write. Collection keys cannot create collections. 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.
Processing flags default to true. At least one flag must stay enabled.
Access control defaults to off. An enforced collection starts with a root rule whose reader list is empty.
A new collection returns 201. exist_ok returns 200 for the existing collection without changing its settings.

Request

https://engine.example.com/namespaces/acme/collections

POST /namespaces/acme/collections HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json
Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7

{
  "name": "incident-logs",
  "display_name": "Incident logs",
  "processing": {
    "keyword": true,
    "semantic": true,
    "graph": true
  },
  "exist_ok": true
}

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

Response

201

A new empty collection.

{
  "id": "col_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "namespace": "acme",
  "name": "incident-logs",
  "display_name": "Incident logs",
  "status": "empty",
  "access_control": "off",
  "processing": {
    "keyword": true,
    "semantic": true,
    "graph": true
  },
  "index_generation": null,
  "file_counts": {
    "pending": 0,
    "indexing": 0,
    "ready": 0,
    "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.

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.

Request body

access_controlstringoptional

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

Default: "off"

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

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

exist_okbooleanoptional

Return the existing collection with status 200 when this name exists. This does not update its settings.

Default: false

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.

processingobjectoptional

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.

Default: {}

Responses

201Collection created

A new empty collection.

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.

Locationstringrequired

The path of the new resource, by ids.

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.

200Collection already exists

exist_ok returned the existing collection without changing it.

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.

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.

409already_exists

The requested resource name already exists.

What to do: Use a new name. Namespace and collection creation also accept exist_ok to return an existing resource.

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.

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