API conventions
Connection
Section titled “Connection”Build requests from ACTERA_BASE_URL and the workspace slug supplied to your application. Authentication headers are environment-specific and must be injected by your server configuration. Keep secrets out of browsers and source control.
All bodies use JSON. Field names use snake_case. Unknown request fields are rejected. Request bodies larger than 1 MiB are rejected.
Identity and request IDs
Section titled “Identity and request IDs”Actera resolves the workspace slug and verifies access. 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 |
The caller cannot access the workspace | Verify workspace selection and membership. |
404 |
The requested record does not exist | Check the identifier in the same 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.