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. The result is 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. An operation held for human approval carries risk_review (risk-based) or its rule's approval hold. Allowed calls carry policy_match, break_glass, approved or endpoint in the audit log.