--- title: Create collection description: Create a collection that holds files and one searchable graph. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Create collection `POST /namespaces/{namespace}/collections` Create a collection that holds files and one searchable graph. **Permission:** Cluster key, or a namespace key with write. Collection keys cannot create collections. [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. 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. ## Example request ```http POST /namespaces/acme/collections HTTP/1.1 Host: engine.example.com Authorization: Bearer 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 } ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. 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. ## Request body ### `access_control` **string · optional** Whether Search and Query 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_name` **string · optional · nullable** Human-readable label. This label does not change the resource name used in URLs. ### `exist_ok` **boolean · optional** Return the existing collection with status 200 when this name exists. This does not update its settings. Default: `false`. ### `name` **string · required** 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. ### `processing` **object · optional** 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: `{}`. #### `processing.graph` **boolean · optional · nullable** Enable graph processing. Omission means true on create and unchanged on update. #### `processing.keyword` **boolean · optional · nullable** Enable keyword Search. Turning this flag on can start a reindex job. Turning it off rejects that Search mode. #### `processing.semantic` **boolean · optional · nullable** Enable semantic Search. Turning this flag on can start a reindex job. Turning it off rejects that Search mode. ## Responses ### 201 · Collection created A new empty collection. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ##### `Location` **string · required** The path of the new resource, by ids. ```json { "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" } ``` #### Response fields ##### `access_control` **string · required** Whether Search and Query 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_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `display_name` **string · required · nullable** Human-readable label. This label does not change the resource name used in URLs. ##### `file_counts` **object · required** Current number of living files in each processing state. ###### `file_counts.failed` **integer · required** Files whose processing failed. ###### `file_counts.indexing` **integer · required** Files whose content is being indexed. ###### `file_counts.pending` **integer · required** Files accepted but waiting for bytes or processing. ###### `file_counts.ready` **integer · required** Files available to Search and Query. ##### `id` **string · required** Immutable collection ID with the col_ prefix. ##### `index_generation` **string · required · nullable** Opaque identifier for the searchable generation. It changes when indexed data changes. Null means that no searchable generation exists. ##### `name` **string · required** 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. ##### `namespace` **string · required** Name of the namespace that contains this collection. ##### `processing` **object · required** 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. ###### `processing.graph` **boolean · required** Whether graph processing is enabled for this collection. ###### `processing.keyword` **boolean · required** Whether lexical Search is enabled for this collection. ###### `processing.semantic` **boolean · required** Whether meaning-based Search is enabled for this collection. ##### `status` **string · required** 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. Query 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_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ### 200 · Collection already exists exist_ok returned the existing collection without changing it. 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": "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" } ``` #### Response fields ##### `access_control` **string · required** Whether Search and Query 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_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `display_name` **string · required · nullable** Human-readable label. This label does not change the resource name used in URLs. ##### `file_counts` **object · required** Current number of living files in each processing state. ###### `file_counts.failed` **integer · required** Files whose processing failed. ###### `file_counts.indexing` **integer · required** Files whose content is being indexed. ###### `file_counts.pending` **integer · required** Files accepted but waiting for bytes or processing. ###### `file_counts.ready` **integer · required** Files available to Search and Query. ##### `id` **string · required** Immutable collection ID with the col_ prefix. ##### `index_generation` **string · required · nullable** Opaque identifier for the searchable generation. It changes when indexed data changes. Null means that no searchable generation exists. ##### `name` **string · required** 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. ##### `namespace` **string · required** Name of the namespace that contains this collection. ##### `processing` **object · required** 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. ###### `processing.graph` **boolean · required** Whether graph processing is enabled for this collection. ###### `processing.keyword` **boolean · required** Whether lexical Search is enabled for this collection. ###### `processing.semantic` **boolean · required** Whether meaning-based Search is enabled for this collection. ##### `status` **string · required** 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. Query 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_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 · `already_exists` The requested resource name already exists. Use a new name. Namespace and collection creation also accept exist_ok to return an existing resource. ```json { "error": { "code": "already_exists", "message": "The requested resource name already exists.", "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": {} } } ``` ### 413 · `request_too_large` The JSON request body exceeds 1,048,576 bytes. Reduce the JSON body. Use upload or a URI source for larger file content. ```json { "error": { "code": "request_too_large", "message": "The JSON request body exceeds 1,048,576 bytes.", "request_id": "req_example", "retryable": false, "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 POST "$GRAPHON_ENGINE_URL/namespaces/acme/collections" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: 8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7' \ --data-raw '{ "name": "incident-logs", "display_name": "Incident logs", "processing": { "keyword": true, "semantic": true, "graph": true }, "exist_ok": true }' ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections", data=json.dumps({"name": "incident-logs", "display_name": "Incident logs", "processing": {"keyword": True, "semantic": True, "graph": True}, "exist_ok": True}).encode("utf-8"), headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], "Content-Type": "application/json", "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, method="POST", ) 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", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "8f3c1e2a-4b5d-6e7f-8091-a2b3c4d5e6f7", }, body: JSON.stringify({"name":"incident-logs","display_name":"Incident logs","processing":{"keyword":true,"semantic":true,"graph":true},"exist_ok":true}), }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.