API conventions
The Actera REST API exposes the trusted operations used to authorize AI agent actions, retrieve decision evidence, and report observed activity. These conventions apply to each curated operation in this reference.
Connection
Section titled “Connection”Build requests from ACTERA_BASE_URL using /v1/... paths. Authenticate with the bearer token issued for your Actera environment:
Authorization: Bearer <access-token>GET /v1/workspaces requires authentication but no workspace selector and returns only workspaces accessible to that principal. Every workspace-scoped operation requires exactly one Actera-Workspace-Id header containing the selected UUID. The header selects scope; it never grants access. A workspace outside the credential’s scope remains inaccessible.
All bodies use JSON. Field names use snake_case. Unknown request fields are rejected. Request bodies larger than 1 MiB are rejected.
Workspace scope and request IDs
Section titled “Workspace scope and request IDs”Actera validates the selected UUID and verifies principal membership before establishing trusted internal actor/workspace context. Missing, malformed, nil, duplicate, and comma-combined selectors return 400. Nonexistent and inaccessible workspaces both return 404. Agent IDs identify the configured agent whose policies and fallback apply. Use stable IDs rather than display names.
Send X-Request-ID to correlate a request across systems. Actera generates one when omitted.
Errors
Section titled “Errors”Errors use a compact envelope:
{ "error": "human-readable safe message" }| Status | Meaning | Recovery |
|---|---|---|
400 |
Invalid JSON or request fields | Correct the request before retrying. |
401 |
Authentication is missing or invalid | Correct configured authentication. |
403 |
An operation-level permission check denied the caller | Verify the principal’s role for that operation. |
404 |
A workspace or resource does not exist or is inaccessible | Check the identifier within the selected workspace. |
409 |
Idempotency conflict or invalid lifecycle operation | Do not retry changed input under the same key. |
413 |
Request exceeds 1 MiB | Reduce context to facts needed by policy. |
500 |
Unexpected server failure | Retry cautiously with the same idempotency key. |
503 |
Temporarily unavailable | Honor Retry-After and retry the same request. |
Idempotency
Section titled “Idempotency”Operations that accept idempotency_key use it to identify one logical request. Repeating the same request with the same key returns the existing result. Reusing a key with changed input returns a conflict.
Credentials can be limited to one or more workspaces. Send the workspace header on every scoped operation, including when a credential is limited to a single workspace. Actera validates that the selected workspace is within the authenticated principal’s scope and never infers a default workspace.
Start with Evaluate an action for the authorization request, then use Retrieve a decision to reconcile approval and execution state. The TypeScript SDK maps these wire conventions to camel-cased client inputs.