Skip to main content
POST
/
v1
/
actions
Error
A valid request URL is required to generate request examples
{
  "id": "act_M4qT8YH7xW2pL9nB",
  "status": "pending",
  "url": "<string>",
  "method": "GET",
  "attempts": 1,
  "retries": 50,
  "created_at": "2023-11-07T05:31:56Z",
  "approve": true,
  "deduplicated": true,
  "body": {},
  "headers": {},
  "dedupe": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "next_retry_at": "2023-11-07T05:31:56Z",
  "last_error": "<string>",
  "response_code": 123,
  "response_body": null,
  "duration_ms": 123,
  "approved_at": "2023-11-07T05:31:56Z",
  "approved_by": "<string>",
  "callback": "<string>",
  "idempotency_key": "<string>",
  "retries_remaining": 1,
  "next_retry_in_seconds": 1,
  "actions": [
    "approve"
  ],
  "error": {
    "source": "target",
    "message": "<string>",
    "response_code": 123,
    "response_body": "<unknown>"
  },
  "receipt_url": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Request-Id
string

Optional client request ID. Echoed back on response.

​
Idempotency-Key
string

Deduplicates create-action requests within a 24-hour window.

​
Content-Type
string
required
Pattern: ^application/json(;.*)?$

Body

application/json
​
url
string<uri>
required
​
method
enum<string>
default:POST
Available options:
GET,
POST,
PUT,
PATCH,
DELETE
​
body
object
​
headers
object
​
dedupe
string
​
retries
integer
default:3
Required range: 1 <= x <= 100
​
approve
boolean
default:false
​
sync
boolean
default:false

When true, the request blocks until the action reaches a terminal status (completed, failed, or cancelled) and returns the final action object. Default timeout is 30 seconds (max 120 seconds). Cannot be combined with approve: true.

​
notify
object

Send a magic-link approval email when approve: true. The email contains approve and reject buttons. Requires RESEND_API_KEY to be configured.

​
callback
string<uri>

Response

Existing deduplicated/idempotent action returned

​
id
string
required
Pattern: ^act_[A-Za-z0-9_-]+$
Example:

"act_M4qT8YH7xW2pL9nB"

​
status
enum<string>
required
Available options:
pending,
active,
awaiting_approval,
completed,
failed,
cancelled
​
url
string<uri>
required
​
method
enum<string>
required
Available options:
GET,
POST,
PUT,
PATCH,
DELETE
​
attempts
integer
required
Required range: x >= 0
​
retries
integer
required
Required range: 1 <= x <= 100
​
created_at
string<date-time>
required
​
approve
boolean
required
​
deduplicated
boolean
required
​
body
object
​
headers
object
​
dedupe
string | null
​
started_at
string<date-time> | null
​
finished_at
string<date-time> | null
​
next_retry_at
string<date-time> | null
​
last_error
string | null
​
response_code
integer | null
​
response_body
unknown
​
duration_ms
integer | null
​
approved_at
string<date-time> | null
​
approved_by
string | null
​
callback
string<uri> | null
​
idempotency_key
string | null
​
retries_remaining
integer
Required range: x >= 0
​
next_retry_in_seconds
integer
Required range: x >= 0
​
actions
enum<string>[]

Allowed operations for the current status.

Available options:
approve,
cancel,
retry
​
error
object

Structured error detail present when status is failed.

​
receipt_url
string | null

Shareable URL for this action's receipt page (e.g. /r/rcpt_...). No authentication required — secured by the unguessable receipt token.