--- title: Create access rule description: Create or replace the readers for a folder prefix or one file. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Create access rule `POST /namespaces/{namespace}/collections/{collection}/access-rules` Create or replace the readers for a folder prefix or one file. **Permission:** Cluster key, or a scoped key with write on this collection. [API key types and authentication](/engine/reference/authentication.md). 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. ## Example request ```http POST /namespaces/acme/collections/incident-logs/access-rules HTTP/1.1 Host: engine.example.com Authorization: Bearer Content-Type: application/json { "folder": "/reports/", "readers": [ "user:ada@acme.example" ], "sealed": false } ``` ## Path parameters ### `namespace` **string · required** Namespace name or ns_ ID. It must be visible to this key. ### `collection` **string · required** Collection name or col_ ID within the namespace. It must be visible to this key. ## Request body ### `file` **string · optional · nullable** Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file. ### `folder` **string · optional · nullable** Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file. ### `readers` **array · 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. ### `sealed` **boolean · optional** 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 ### 202 · Rule application accepted A new governing rule affects existing files. Those files stay hidden until this job succeeds. Content type: `application/json`. #### Response headers ##### `x-request-id` **string · required** Request correlation ID. Retain it when investigating a failed or unexpected request. ```json { "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" } } ``` #### Response fields ##### `job` **object · required** Job that applies the rule to affected files. Those files remain hidden from retrieval until it succeeds. ###### `job.collection` **string · optional · nullable** Collection name when this job belongs to a collection. Otherwise omitted. ###### `job.created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ###### `job.error` **object · required · nullable** Failure details, or null when no failure is recorded. ###### `job.error.code` **string · required** Machine-readable reason for the failure. Use this value for program logic and message for display or diagnostics. ###### `job.error.message` **string · required** Human-readable explanation of the failure. Do not parse this text to decide how to retry. ###### `job.file_id` **string · optional · nullable** File ID when this job acts on one file. Otherwise omitted. ###### `job.id` **string · required** Immutable job ID with the job_ prefix. Use it to read the current state. ###### `job.namespace` **string · optional · nullable** Namespace name when this job belongs to a namespace. ###### `job.status` **string · required** Current state of the asynchronous work. succeeded, failed, and canceled are terminal states. - `queued`: Accepted and waiting to start. - `running`: Work is in progress. - `succeeded`: Work completed successfully. - `failed`: Work ended with an error. - `canceled`: Work ended after cancellation. ###### `job.type` **string · required** Kind of work accepted by the API. - `index_file`: Index a new or replacement file. - `delete_file`: Remove a file and clean its derived data. - `reindex_collection`: Rebuild the collection’s derived data. - `delete_collection`: Remove a collection and its derived data. - `delete_namespace`: Remove a namespace and its collections. - `apply_access_rule`: Apply changed governing rules to affected files. ###### `job.updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ##### `rule` **object · required** Access rule after the accepted change. ###### `rule.created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ###### `rule.file` **string · optional · nullable** Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file. ###### `rule.folder` **string · optional · nullable** Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file. ###### `rule.id` **string · required** Immutable access-rule ID with the acr_ prefix. ###### `rule.readers` **array · 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. ###### `rule.sealed` **boolean · required** Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file. ###### `rule.updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ### 201 · Rule created A new rule targets a path with no existing files. 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": "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" } ``` #### Response fields ##### `created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `file` **string · optional · nullable** Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file. ##### `folder` **string · optional · nullable** Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file. ##### `id` **string · required** Immutable access-rule ID with the acr_ prefix. ##### `readers` **array · 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. ##### `sealed` **boolean · required** Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file. ##### `updated_at` **string (date-time) · required** Time the resource last changed, as an ISO 8601 UTC timestamp. ### 200 · Readers replaced Only the readers of an existing rule changed. The change applies on the next request. 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": "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" } ``` #### Response fields ##### `created_at` **string (date-time) · required** Time the resource was created, as an ISO 8601 UTC timestamp. ##### `file` **string · optional · nullable** Exact file path, such as /reports/incident.txt. Send exactly one of file and folder. The rule may exist before the file. ##### `folder` **string · optional · nullable** Folder prefix, such as /reports/. Start and end with /. The root / covers the collection. Send exactly one of folder and file. ##### `id` **string · required** Immutable access-rule ID with the acr_ prefix. ##### `readers` **array · 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. ##### `sealed` **boolean · required** Whether this folder rule overrides every rule below it. Only folder rules can be sealed. The highest sealed ancestor governs a file. ##### `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 · `operation_in_progress` An unfinished operation conflicts with this request. Inspect the existing job and wait for its completion event before retrying. ```json { "error": { "code": "operation_in_progress", "message": "An unfinished operation conflicts with this request.", "request_id": "req_example", "retryable": true, "details": {} } } ``` ### 409 · `limit_exceeded` The operation would exceed a documented size or count limit. Reduce the input or resource count. This is not a tenant billing limit. ```json { "error": { "code": "limit_exceeded", "message": "The operation would exceed a documented size or count limit.", "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/incident-logs/access-rules" \ -H "Authorization: Bearer $GRAPHON_ENGINE_API_KEY" \ -H 'Content-Type: application/json' \ --data-raw '{ "folder": "/reports/", "readers": [ "user:ada@acme.example" ], "sealed": false }' ``` ### Python ```python import json import os import urllib.request request = urllib.request.Request( os.environ["GRAPHON_ENGINE_URL"] + "/namespaces/acme/collections/incident-logs/access-rules", data=json.dumps({"folder": "/reports/", "readers": ["user:ada@acme.example"], "sealed": False}).encode("utf-8"), headers={ "Authorization": "Bearer " + os.environ["GRAPHON_ENGINE_API_KEY"], "Content-Type": "application/json", }, 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/incident-logs/access-rules", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GRAPHON_ENGINE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"folder":"/reports/","readers":["user:ada@acme.example"],"sealed":false}), }); console.log(response.status, await response.text()); ``` ## Sitemap See the full [sitemap](/sitemap.md) for all pages.