REST API Reference

The ActionBox REST API is hosted over HTTPS at:

https://api.actionbox.cloud

The live OpenAPI document is the authoritative contract for every route, field, enum, and response. The examples below show the public Action workflow and omit fields that are not relevant to the example.

Authentication

Machine integrations use a Source key in the Authorization header. Use the live key (axb_live_…) for live Actions or the test key (axb_test_…) for sandbox Actions:

Authorization: Bearer axb_live_…

User-scoped inbox and workspace operations use a signed user session bearer token (axb_usr_…) or the browser's secure actionbox_session cookie. Never put a Source key, user token, or webhook secret in browser JavaScript, a URL, logs, screenshots, or source control. See API Authentication for credential boundaries and key rotation.

Create an Action

POST /v1/actions requires a Source key and returns 201 Created. Send a stable Idempotency-Key for a logical operation so an uncertain transport retry cannot create a duplicate Action.

POST /v1/actions HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_live_…
Idempotency-Key: deploy-build-42
Content-Type: application/json

{
  "title": "Deploy v2.18 to production?",
  "description": "The staging checks passed; review before shipping.",
  "priority": "high",
  "options": [
    {"id": "approve", "label": "Approve & deploy", "style": "primary"},
    {"id": "reject", "label": "Reject & abort", "style": "destructive"}
  ],
  "expires_at": "2026-09-01T22:00:00Z",
  "metadata": {"build_id": "job_124"}
}

options is the concise single-choice form and is mutually exclusive with a typed interaction. You can instead provide one of the supported interaction types described in Interaction and decision types. callback_url, when supplied, must be an HTTPS callback destination that is reachable on the public internet; it is set when the Action is created and is not a field on the patch endpoint. metadata is limited to 32 KB, and the complete create or patch body is limited to 256 KB.

The response is wrapped in data and includes the version binding used for safe decisions (abbreviated here):

{
  "data": {
    "id": "act_99f2b801a",
    "status": "open",
    "environment": "live",
    "title": "Deploy v2.18 to production?",
    "description": "The staging checks passed; review before shipping.",
    "priority": "high",
    "action_version": 1,
    "fingerprint": "sha256:<64 lowercase hex characters>",
    "options": [
      {"id": "approve", "label": "Approve & deploy", "style": "primary", "sort_order": 0},
      {"id": "reject", "label": "Reject & abort", "style": "destructive", "sort_order": 1}
    ],
    "interaction": null,
    "response": null,
    "resolution_option_id": null,
    "resolution_reason": null,
    "receipt": null,
    "outcome": null,
    "created_at": "2026-08-28T04:20:00+00:00",
    "expires_at": "2026-09-01T22:00:00+00:00"
  },
  "idempotent_replay": false
}

Read the current Action

Machine code should use the Source-scoped route:

GET /v1/source/actions/act_99f2b801a?wait_seconds=30 HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_live_…

wait_seconds is optional and accepts 0 through 30. It is a bounded server wait, not a decision; an Action can still be open when the request returns. The response uses the same Action shape as the create response and includes response, resolution_option_id, resolution_reason, receipt, and outcome when those values exist.

For a signed-in human inbox, use GET /v1/me/actions to list Actions and GET /v1/actions/{action_id} to read one with its user-visible history. Use environment=test when listing or reading sandbox Actions; the default is live.

Update an open Action

PATCH /v1/actions/{action_id} requires the owning Source key. It accepts updates to title, description, priority, open_url, expires_at, on_expire, context, decision_class, decision_context, and metadata. Updating material content advances action_version and changes fingerprint, so a reviewer must use the latest snapshot before deciding.

PATCH /v1/actions/act_99f2b801a HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_live_…
Content-Type: application/json

{"description": "The rollback check also passed."}

Only open Actions can be updated. The create-only fields options, interaction, and callback_url cannot be changed after creation.

Resolve or cancel from software

Machine resolution is different from a human decision: it records the owning Source as the resolver. Use POST /v1/actions/{action_id}/resolve only when software has determined that the Action no longer needs a human answer. Include the reviewed binding when resolving from a snapshot:

POST /v1/actions/act_99f2b801a/resolve HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_live_…
Content-Type: application/json

{
  "option_id": "approve",
  "action_version": 1,
  "fingerprint": "sha256:<64 lowercase hex characters>",
  "reason": "The deployment was superseded by an automated rollback."
}

To cancel an open Action from the owning Source, call POST /v1/actions/{action_id}/cancel:

{"reason": "The pipeline was superseded by a newer run."}

Only the first terminal transition wins. Later attempts return a conflict and do not rewrite the Action history.

Record execution outcome

After a resolved Action's operation has actually run, the owning Source can report one immutable execution result with POST /v1/actions/{action_id}/outcome:

{
  "status": "success",
  "duration_ms": 48312,
  "rollback": false,
  "action_version": 1,
  "fingerprint": "sha256:<64 lowercase hex characters>"
}

status is success or failed. Keep the same fields and idempotency key for an exact retry; a different second outcome is rejected. An execution outcome does not change the human decision recorded on the Action.

Human decisions

The signed-in human surface uses POST /v1/actions/{action_id}/decision with the same option_id or typed response fields and the action_version and fingerprint from the displayed snapshot:

{
  "action_version": 1,
  "fingerprint": "sha256:<64 lowercase hex characters>",
  "option_id": "approve",
  "reason": "Staging checks and rollback plan reviewed."
}

The route requires a user session, validates the interaction, and returns the resolved Action. A stale binding returns 409 ACTION_CHANGED; fetch the current Action and require a fresh review. See Decision receipts for offline verification of the signed receipt on a newly resolved Action.

Error envelope and status codes

Errors use one stable envelope. The X-Request-ID response header is safe to record with the endpoint and status, but never log credentials or customer content:

{
  "error": {
    "code": "ACTION_CHANGED",
    "message": "This Action changed while it was being reviewed.",
    "details": {}
  }
}

Common Action API errors include:

See Errors and safe retries and the live OpenAPI document for the complete contract.