Skip to main content
POST
Execute action

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

action
Action · object
required

Action to execute.

data
any

Input data for the run.

waitUntilFinished
boolean

When true, the request blocks until the run reaches a terminal status, up to 5 minutes. On timeout the run keeps running and the response is 408.

webhookUrl
string<uri>

URL to call when the run completes.

webhookSecret
string

Secret used to sign webhook deliveries. When provided, Cargo includes an X-Cargo-Signature header (sha256=) so you can verify the payload.

Response

Run finished within the wait window. Returned only when waitUntilFinished is true.

run
Run · object
required

Created run details.

runComputedConfigs
Run computed configs · object

Computed configuration values for the run. Present when waitUntilFinished is true.

runContext
Run context · object

Context values captured for the run. Present when waitUntilFinished is true.