Skip to main content
POST
Run a command

Authorizations

Authorization
string
header
required

An API token for one organization. You create and revoke tokens in the dashboard. A token scoped to one App can reach only that App, so give that kind of token to an agent. An organization-wide token can create a short-lived one with POST /api/tokens.

Scopes

apps:write
OAuth

Change the organization's Apps: edit files, run commands, deploy, and manage Secrets.

apps:write
DPoP

Headers

Idempotency-Key
string

A key that identifies this request for retries, up to 200 printable characters. A retry with the same key and input returns the first request's result instead of repeating the work. If you omit the key, the API generates one and returns it in the Idempotency-Key response header.

Required string length: 1 - 200

Path Parameters

id
string
required

A unique ID that starts with app_.

Pattern: ^app_[0-9A-Za-z]{24}$
Example:

"app_Zj7XhMgplmTJcp5Dk4vcYuk0"

Body

application/json
command
string
required

The shell command to run, up to 8192 characters.

Required string length: 1 - 8192
timeout_seconds
integer
default:60

How long the command can run, in seconds, before it's stopped.

Required range: 1 <= x <= 120

Response

The command's result.

id
string
required

The command's action ID, which starts with act_.

app_id
string
required

The ID of the App that ran the command.

status
enum<string>
required

How the command ended:

  • completed: the command exited, and exit_code holds its exit code.
  • timed_out: the command ran past timeout_seconds and was stopped.
  • interrupted: the command ended without a result, for example because the sandbox was lost. Its effects are unknown, and it's never run again.
Available options:
completed,
timed_out,
interrupted
exit_code
integer | null
required

The command's exit code, or null if it was interrupted.

Example:

0

output
string
required

The command's captured output, up to the output limit. If the command was interrupted, the output is partial.

truncated
boolean
required

True if the output passed the limit and was cut off; false otherwise.

started_at
string<date-time>
required

When the command started.

Example:

"2026-10-03T14:01:30.000Z"

finished_at
string<date-time>
required

When the command ended.

Example:

"2026-10-03T14:01:30.000Z"