Create namespace

Create a tenant isolation boundary that will contain collections.

POST/namespaces

PermissionCluster key. 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.
A new namespace returns 201. exist_ok returns 200 when the name already exists, without changing that namespace.
Usage counts describe resources and storage. Applications own tenant plan limits.

Request

https://engine.example.com/namespaces

POST /namespaces 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": "acme",
  "display_name": "Acme",
  "exist_ok": true
}

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

Response

201

A new namespace with zero usage.

{
  "id": "ns_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "name": "acme",
  "display_name": "Acme",
  "usage": {
    "collections": 0,
    "files": 0,
    "source_bytes": "0",
    "index_bytes": "0"
  },
  "created_at": "2026-10-06T10:00:00Z",
  "updated_at": "2026-10-06T10:00:00Z"
}

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

display_namestringoptionalaccepts null

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

exist_okbooleanoptional

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

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.

Responses

201Namespace created

A new namespace with zero usage.

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.

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.

idstringrequired

Immutable namespace ID with the ns_ prefix.

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.

updated_atstring (date-time)required

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

usageobjectrequired

Current resource counts and storage usage. These are measurements, not tenant plan quotas.

200Namespace already exists

exist_ok returned the existing namespace 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.

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.

idstringrequired

Immutable namespace ID with the ns_ prefix.

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.

updated_atstring (date-time)required

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

usageobjectrequired

Current resource counts and storage usage. These are measurements, not tenant plan quotas.

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.

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