Broker API reference

Agents talk to the broker over HTTP with Authorization: Bearer <token>, where the token is a workload-identity JWT or an agent token.

Endpoints

Method and path	Purpose
POST /v1/actions	Perform an operation
POST /v1/authorize	Dry-run a policy decision (no rate-limit cost)
GET /v1/actions/{id}	Poll an operation waiting for approval
POST /e/{id}	Call a published endpoint (endpoint key)
GET /e/{id}/actions/{req}	Poll an approval-gated endpoint call
GET /v1/providers	List providers and actions
GET /v1/usage	Usage against the plan
GET /v1/custody/pubkey	The broker's public key and algorithm
GET /healthz	Liveness

Perform an operation

POST /v1/actions
{"provider": "cloudflare", "resource": "example.com", "action": "DNS_READ",
 "parameters": {"type": "A"}}

Success returns 200:

{"success": true, "operation": "DNS_READ", "resource": "example.com",
 "data": {...}, "request_id": "8a41d0c2"}

Status codes

Code	Meaning
200	Performed; result in the body
202	approval_required, pending or executing; poll the given path
400	Malformed request or unknown provider
401	Missing, invalid, expired or replayed identity token
403	Denied; reason says why
429	Plan quota reached
500	The credential could not be obtained
502, 504	The provider failed or timed out

Deny reasons

lockdown, guardrail_deny, explicit_deny, unknown_agent, no_matching_rule, action_not_allowed, constraint_violation, rate_limited. Allowed calls carry policy_match, break_glass, approved or endpoint in the audit log.