Create access rule

Create or replace the readers for a folder prefix or one file.

POST/namespaces/{namespace}/collections/{collection}/access-rules

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

Access rules require an enforced collection. Rule targets use logical paths. API-key actions control writes independently of these reader rules.
A new rule over no files returns 201. A reader-only replacement returns 200 and applies on the next request.
A change to the governing rule of existing files returns 202 with a rule and job. Affected files stay hidden until the job succeeds.
Send exactly one target. A file rule cannot be sealed.

Request

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

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

{
  "folder": "/reports/",
  "readers": [
    "user:ada@acme.example"
  ],
  "sealed": false
}

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

Response

202

A new governing rule affects existing files. Those files stay hidden until this job succeeds.

{
  "rule": {
    "id": "acr_01K6Q6N7D8E9F0G1H2J3K4M5N6",
    "folder": "/reports/",
    "readers": [
      "user:ada@acme.example"
    ],
    "sealed": false,
    "created_at": "2026-10-06T10:00:00Z",
    "updated_at": "2026-10-06T10:00:00Z"
  },
  "job": {
    "id": "job_01K6Q6N7D8E9F0G1H2J3K4M5N6",
    "type": "apply_access_rule",
    "status": "running",
    "namespace": "acme",
    "collection": "incident-logs",
    "error": null,
    "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

filestringoptionalaccepts null

Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file.

folderstringoptionalaccepts null

Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file.

readersarray<string>required

User or group principals allowed by this rule. Principals match exact strings. Maximum 1,024 readers, each at most 256 UTF-8 bytes. An empty list denies retrieval.

sealedbooleanoptional

Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file.

Default: false

Responses

202Rule application accepted

A new governing rule affects existing files. Those files stay hidden until this job succeeds.

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.

jobobjectrequired

Job that applies the rule to affected files. Those files remain hidden from retrieval until it succeeds.

ruleobjectrequired

Access rule after the accepted change.

201Rule created

A new rule targets a path with no existing files.

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.

filestringoptionalaccepts null

Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file.

folderstringoptionalaccepts null

Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file.

idstringrequired

Immutable access-rule ID with the acr_ prefix.

readersarray<string>required

User or group principals allowed by this rule. Principals match exact strings. Maximum 1,024 readers, each at most 256 UTF-8 bytes. An empty list denies retrieval.

sealedbooleanrequired

Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file.

updated_atstring (date-time)required

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

200Readers replaced

Only the readers of an existing rule changed. The change applies on the next request.

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.

filestringoptionalaccepts null

Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file.

folderstringoptionalaccepts null

Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file.

idstringrequired

Immutable access-rule ID with the acr_ prefix.

readersarray<string>required

User or group principals allowed by this rule. Principals match exact strings. Maximum 1,024 readers, each at most 256 UTF-8 bytes. An empty list denies retrieval.

sealedbooleanrequired

Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file.

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.

409limit_exceeded

The operation would exceed a documented size or count limit.

What to do: Reduce the input or resource count. This is not a tenant billing limit.

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