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 live Source key (axb_live_…) in the Authorization header:

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. The complete evidence and secondary-operation shapes are in Context block schemas, Decision context, and Action Controls. To route the Action, add either assignee_email or assignee_user_id. Copy a member ID from Settings → Team. The assignment schema and client matrix show the rules without repeating the full create schema here. Team integrations may instead set visibility to restricted and provide one non-empty list, reviewer_emails or reviewer_user_ids (up to 15). See restricted reviewer routing for access, assignment, and notification behavior. Team Sources can add approval_policy to a restricted boolean or two-option Action. Human reviewers then use POST /v1/actions/{action_id}/votes with an Idempotency-Key; /decision returns APPROVAL_VOTE_REQUIRED. See the complete Approval Policies contract. 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. context_request_mode defaults to unsupported; poll declares an Action-reading Source and callback declares a handler for signed action.context_requested events. Callback mode requires callback_url. 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. The default inbox lists live Actions owned by the active workspace.

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, controls, 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.

Action Controls

Add controls when creating an Action, or replace them on an open Action with PATCH /v1/actions/{action_id}. An Action accepts up to 12 controls and no more than three mutating controls. A callback control requires the Action's create-only callback_url; a link control opens its own HTTP or HTTPS URL and does not create a Control Request.

A signed-in reviewer invokes a callback control with the current Action binding and a stable idempotency key:

POST /v1/actions/act_99f2b801a/controls/retry/invoke HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_usr_…
Idempotency-Key: retry-import-4821
Content-Type: application/json

{
  "action_version": 3,
  "fingerprint": "sha256:<64 lowercase hex characters>"
}

The API returns 202 Accepted with the Control Request in data. An identical retry returns the original request with idempotent_replay: true. Read recent requests visible to the signed-in workspace with:

GET /v1/actions/act_99f2b801a/control-requests

ActionBox sends the owning Source a signed action.control_requested webhook. After allowlisting the control key and performing the bounded operation, the Source reports its state without resolving the parent Action:

POST /v1/source/control-requests/ctr_123/result HTTP/1.1
Host: api.actionbox.cloud
Authorization: Bearer axb_live_…
Content-Type: application/json

{
  "status": "succeeded",
  "message": "Import resumed"
}

status is running, succeeded, or failed. See Action Controls for the complete field schema, destructive-control behavior, webhook lifecycle, result reporting, CLI, MCP, and SDK support.

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. See Decisions and outcomes for the distinction between authorization and the result of the operation.

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.