Actions API

API reference for action endpoints.

Submit Action

Request body:

{
  "agent_id": "my-agent",
  "tool": "shell",
  "operation": "exec",
  "params": {"cmd": "echo hello"},
  "context": {"approval_email": "admin@example.com"}
}

{
  "agent_id": "my-agent",
  "tool": "shell",
  "operation": "exec",
  "params": {"cmd": "echo hello"},
  "context": {"approval_email": "admin@example.com"}
}

{
  "agent_id": "my-agent",
  "tool": "shell",
  "operation": "exec",
  "params": {"cmd": "echo hello"},
  "context": {"approval_email": "admin@example.com"}
}

Field	Type	Required	Description
agent_id	string	Yes	Agent identifier
tool	string	Yes	Tool name (shell, github, stripe, etc.)
operation	string	No	Operation (op is alias)
params	object	No	Tool-specific parameters
context	object	No	Metadata (approval_email for notification recipient, etc.)

Response: Action object. Key fields:

Field	Description
id	Action UUID
status	e.g. `pending_approval`, `allowed`, `denied`, `succeeded`, `failed`
decision	`EXECUTE`, `ABSTAIN`, or `HALT`
reason	Human-readable reason (e.g. which rule matched or "No rule matched")
reason_code	Optional machine-readable code (e.g. `POLICY_ALLOW`, `DEFAULT_DENY_NO_MATCH`)
request_hash	SHA-256 of canonical action (for audit/replay)
risk_level	`low`, `medium`, or `high`
approval_token	Present when `status` is `pending_approval`; use when calling the approval endpoint
policy_hash, provenance_id	Version binding for audit

List Actions

Query params:

Param	Description
status	Filter by status (pending_approval, allowed, denied, succeeded, failed)
agent_id	Filter by agent
tool	Filter by tool
limit	Max results (default varies)
offset	Pagination offset

Response: Array of action objects.

Get Action

Response: Full action object.

Approve or Deny

Request body:

{
  "token": "approval-token-from-action",
  "approve": true,
  "reason": "Approved for deployment"
}

{
  "token": "approval-token-from-action",
  "approve": true,
  "reason": "Approved for deployment"
}

{
  "token": "approval-token-from-action",
  "approve": true,
  "reason": "Approved for deployment"
}

Field	Type	Required	Description
token	string	Yes	Single-use approval token
approve	boolean	Yes	true = approve, false = deny
reason	string	No	Reason for audit

Response: Updated action object.

Errors

Code	HTTP	Meaning
invalid_action	400	Malformed or invalid request body (e.g. missing required fields, invalid types)
not_found	404	Action ID does not exist
invalid_state	409	Action is not in the right status (e.g. approving when not pending_approval, or posting result when not executing)
unauthorized	401	Missing or invalid API key
forbidden	403	Not allowed to perform this operation

Response body includes error, code, and optional detail. Use the interactive docs at /docs for full schemas.

Table of content