Creating Actions
Create typed, durable human decision requests with expiration, callbacks, and safe retries.
Actions are durable decision requests. Create one with a scoped Source key by
posting to https://api.actionbox.cloud/v1/actions, or use the ActionBox CLI
or SDK. An Action starts open and stays authoritative in the API until it is
resolved, cancelled, or expired.
Create a decision request
This example uses the concise options form for a single-choice decision:
{
"title": "Deploy release 2.18 to production?",
"description": "Staging checks passed. Review the release before changing production.",
"priority": "high",
"options": [
{ "id": "approve", "label": "Approve and deploy", "style": "primary" },
{ "id": "hold", "label": "Hold", "style": "default" }
],
"callback_url": "https://your-service.example.com/actionbox/callback",
"expires_at": "2026-12-31T18:00:00Z",
"metadata": {
"release": "2.18",
"environment": "production"
}
}Send it with a Source key in the Authorization header:
curl -X POST https://api.actionbox.cloud/v1/actions \
-H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY" \
-H "Idempotency-Key: deploy-release-2-18" \
-H "Content-Type: application/json" \
-d @action.jsonRequest fields
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Human-readable summary, 1–200 characters. |
description | string | No | Free-form details or instructions, up to 10,000 characters. |
priority | string | No | low, normal, high, or urgent; defaults to normal. Priority orders the open inbox and can be used by notification policy. |
options | array | No | Concise single-choice shorthand with at most 3 unique {id, label, style} options. Styles are default, primary, or destructive. |
interaction | object | No | One typed interaction. It is mutually exclusive with options; see Interaction and decision types. |
callback_url | string | No | Public HTTPS endpoint for a signed webhook when the Action reaches a terminal state. |
expires_at | string | No | Future RFC 3339 timestamp. By default, the Action becomes expired; an explicit on_expire response can choose a typed fallback instead. |
on_expire | object | No | Defaults to {"type":"return_expired"}; {"type":"resolve","response":...} can record a predefined typed fallback when the deadline passes. |
open_url | string | No | HTTP(S) URL the reviewer can open for additional context. |
dedupe_key | string | No | Up to 255 characters. A repeat request updates the existing open Action for that Source instead of creating another one. |
context | array | No | Up to 12 typed review-context blocks such as diff, code, logs, json, metrics, links, or command. Account plan limits may be stricter than the schema ceiling. |
decision_context | object | No | Structured reason, proposed change, risk, reversibility, and optional affected scope for the reviewer. |
metadata | object | No | Customer-defined JSON metadata, up to 32 KB. Do not put credentials or secrets here. |
If both options and interaction are omitted, the Action is informational.
The dashboard presents an Acknowledge control and accepts an empty decision;
it does not invent Approve and Reject choices.
Callbacks must be safe to receive
ActionBox accepts callback URLs over public HTTPS only. Verify the HMAC signature and timestamp over the exact raw request body, then deduplicate by event ID before doing work. A callback reports a terminal Action event; it does not prove that your operation succeeded.
Idempotency and safe retries
Network drops and pipeline retries should reuse the same Idempotency-Key for
the same logical create request:
curl -X POST https://api.actionbox.cloud/v1/actions \
-H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY" \
-H "Idempotency-Key: deploy-release-2-18" \
-H "Content-Type: application/json" \
-d @action.json24-hour replay protection
ActionBox retains a Source-scoped idempotency key for 24 hours. Repeating the
same key with the same request returns the original Action in data and sets
idempotent_replay to true; it does not create a second Action. Reusing a
key with a different request returns 409 IDEMPOTENCY_KEY_REUSED.
Priority and notifications
Priority is a routing signal, not an execution guarantee:
- The open Inbox orders Actions
urgent,high,normal, thenlow. - A workspace policy can select which priorities escalate to owners and admins.
- Each user can select which priorities are eligible for push delivery and can configure quiet hours.
Push delivery can be delayed or unavailable. Always read the Action state from the API before acting.
Next: Interaction and decision types, Decisions and outcomes, or Webhooks and callbacks.