Batch access rules

Apply multiple access-rule changes atomically.

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

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.
Send Idempotency-Key. Retry the same logical request with the same key and body. Idempotency records remain available for replay for 24 hours.
Every operation commits, or none does. Invalid operations fail the whole batch. Error details identify the failed operation.
Reader-only batches return 200. A batch that changes governing rules returns 202 with one job. Affected targets remain hidden until it succeeds.

Request

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

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

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

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

Response

202

At least one change affects governing rules. One job applies the batch.

{
  "rules": [
    {
      "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.

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

operationsarray<object>required

Ordered rule operations that commit together. Every operation succeeds, or none does. The 1 MiB JSON body limit bounds the batch.

Responses

202Batch application accepted

At least one change affects governing rules. One job applies the batch.

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.

jobobjectoptionalaccepts null

Present when the batch changes which rule governs files. Affected files remain hidden until this job succeeds.

rulesarray<object>required

Rules left by upsert and update operations, in operation order. Deleted rules are omitted.

200Readers updated

A reader-only batch 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.

jobobjectoptionalaccepts null

Present when the batch changes which rule governs files. Affected files remain hidden until this job succeeds.

rulesarray<object>required

Rules left by upsert and update operations, in operation order. Deleted rules are omitted.

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.

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.

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