Publish a policy
const url = 'https://example.com/v1/policies';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"id":"example","tenantId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","version":"example","kind":"access-control","description":"example","spec":{}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/policies \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "id": "example", "tenantId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": "example", "kind": "access-control", "description": "example", "spec": {} }'Body is a full Policy — the server validates top-level shape (id, tenantId, semver version, kind ∈ closed enum, spec is an object), and spec for tool-errors, hitl and retention (a retention policy with an unknown domain or mode: archive is refused with 400 validation-failed, naming the field). Other kinds’ specs are their runtime consumer’s to validate. Re-publishing an existing (policyId, version) returns 409 policy-already-registered. A tenant has one retention policy per domain, plus one for *: a second policy id for a covered domain is refused with 409 policy-scope-taken (details.heldBy names the policy that covers it; publish a new version of that one instead), and a new version can’t move a policy to another domain (409 policy-scope-changed). Where this server has a retention limit for a domain, a policy for that domain that keeps its rows longer, or holds them (graceSeconds: -1), is refused with 400 retention-over-limit (details.limitSeconds is the limit); a * policy isn’t, as the server caps each limited domain when it sweeps. A known kind that no runtime consumer applies yet (access-control, adapter-allowlist, rate-limit, compliance) is refused with 400 kind-not-applied (details.appliedKinds lists the ones that are): publishing it would change nothing. Idempotency-Key applies (retries with the same key replay the original 201).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Optional. When present, must match the caller tenant (server-derived from the token). Cross-tenant publish is rejected.
object
Responses
Section titled “Responses”Policy published.
object
Examplegenerated
{ "policyId": "example", "version": "example"}Validation failed (see details.issues); kind-not-applied: no runtime consumer applies that kind yet; or retention-over-limit: the retention policy keeps its domain’s rows longer than this server’s limit, or holds them (details.limitSeconds).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}policy-already-registered: that (id, version) exists. policy-scope-taken: another policy covers the retention domain (details.heldBy). policy-scope-changed: the version would move the policy to another domain.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}