API conventions

The production API is served at https://app.actera.dev. The TypeScript SDK uses this address automatically; direct HTTP examples include it explicitly. Authenticate agent requests with their connection key:

Authorization: Bearer <ACTERA_API_KEY>
Content-Type: application/json

The key supplies the workspace and permitted agent identity. Do not send an Actera-Workspace-Id header from a machine integration. If a request includes an agent ID, it must match the key.

Connection keys authorize agent operations. They do not provide unrestricted decision browsing or human approval authority. Use Actera’s Decisions and Needs approval pages for those tasks.

JSON and identifiers

Request fields use snake_case; the TypeScript SDK accepts camel-cased input options where documented. Use stable IDs, not display names. Timestamps use RFC 3339.

Unknown request fields are rejected. Keep request bodies below 1 MiB and include only relevant context. Monetary sums and counters should use exact integers with consistent units.

Send X-Request-ID when you need to correlate a request with your application logs; Actera supplies one if omitted.

Errors

API errors use structured JSON:

{
  "code": "InvalidArgument",
  "message": "The request is invalid.",
  "field_errors": []
}

Validation errors may include field-specific messages. Handle status and code rather than matching message text.

HTTP status	Meaning	Recovery
400	Invalid input	Correct the request before retrying.
401	Missing, expired, or invalid authentication	Check the connection and configured key.
403	Operation not permitted	Check the credential’s authority.
404	Resource missing or inaccessible	Check the ID and agent connection.
409	Conflicting input or invalid lifecycle transition	Reconcile the existing request before taking further action.
413	Request too large	Reduce the input to relevant facts.
429	Rate, capacity, or plan allowance reached	Honor Retry-After and check Plan & usage.
500	Unexpected server error	Retry cautiously with the original idempotency key.
503	Temporarily unavailable	Honor Retry-After; retry with the same input and key.

An error response grants no permission to execute. Keep the action paused or stopped according to your integration’s configured failure behavior.

Idempotency and retries

Use one stable idempotency_key for one logical action. Repeating a resolved request returns the original decision. Changing input or mode under the same key causes a conflict.

A lost response is not a reason to create a new key. Retry the original request. Retries remain subject to rate and plan limits.

Outcome reports have their own idempotency keys. Retry a report with exactly the same key and body. A later, different outcome uses a new report key.

Actera’s idempotency does not deduplicate external provider calls. Preserve a separate provider idempotency key and application recovery state. Managed execution adds a claim and report flow through the SDK.