API Overview

The AXON Decision daemon is a self-hosted HTTP server that handles policy evaluation, payment signing, approvals, and treasury operations. Default base URL: http://127.0.0.1:3030

Authentication

AXON recognizes three credential classes on authenticated /v1/* routes:

Operator key
Tenant API key
Supabase session

The static AXON_DECISION_API_KEY. Full trust. Required for:

Operator-only REST routes under /v1/operator/* and all /v1/repair/* endpoints
Provider registry mutations (/v1/providers/*)
Worker triggers (/v1/webhooks/dispatch, /v1/transactions/confirm, /v1/approvals/expire)
Global metrics (/v1/metrics)

Authorization: Bearer <AXON_DECISION_API_KEY>

This key can call many org-scoped routes, but it is not bound to an organization. Routes that require an org context, such as GET /v1/me, return 404 NOT_FOUND.

Database-backed keys of the form axon_sk_..., stored hashed in api_keys. Each key is scoped to one organization_id and has read/write scopes. Keys may also be bound to a single wallet_id.

Org-wide keys resolve to the operator capability surface.
Wallet-bound keys resolve to the runtime capability surface.

Authorization: Bearer axon_sk_<...>

When AXON_PLATFORM_AUTH_ENABLED=true, the daemon accepts a Supabase user access token on supported browser-facing org routes. The daemon validates the JWT, loads user_organizations, and grants org-scoped access matching the user’s memberships.

Public routes do not require a bearer token:

GET /health
GET /ready
GET /v1/health
GET /v1/ready
GET /v1/
GET /v1/discovery/resources
POST /v1/services/:id/quote

POST /v1/orgs/bootstrap/browser is also guarded by AXON_HOSTED_BROWSER_BOOTSTRAP_DISABLED; when that flag is true, the route returns 403 even for valid browser sessions.

Error Format

All AXON errors return structured payloads:

{
  "code": "APPROVAL_REQUIRED",
  "message": "Payment escalated for human approval.",
  "recoverable": true,
  "suggested_action": "Approve in dashboard, then call check_approval_status to retrieve approval_token, then retry governed_fetch with approval_token.",
  "details": {
    "decision_id": "..."
  }
}

HTTP Status Codes

Status	Meaning
`400`	Validation failures, `WALLET_BINDING_REQUIRED`, and some recoverable route errors
`401`	`UNAUTHENTICATED` or `INVALID_API_KEY`
`403`	Policy or capability-surface rejection
`404`	Resource not found
`409`	Approval or idempotency conflict
`429`	Rate limited
`500`	Non-recoverable or internal failure
`502` / `503` / `504`	Selected upstream, circuit-breaker, or timeout failures

Malformed JSON is a special case: the daemon returns a JSON-RPC parse envelope with error.code = -32700 even on REST routes.

Surface split

AXON exposes two capability surfaces:

runtime: wallet-scoped spend, approvals, receipts, and runtime MCP tools
operator: org-scoped control-plane operations such as wallets, offers, keys, mandates, treasury, and operator MCP tools

The important part is that the surface is derived from the credential shape, not from client convention.

Endpoint Summary

Public

Method	Path	Purpose
`GET`	`/health`	Liveness check
`GET`	`/ready`	Readiness check (DB, wallet, mandate, workers)
`GET`	`/v1/health`	Public alias for `/health`
`GET`	`/v1/ready`	Public alias for `/ready`
`GET`	`/v1/`	Public catalog of discovery and operator-list endpoints
`GET`	`/v1/discovery/resources`	Public Bazaar feed
`POST`	`/v1/services/:id/quote`	Public quoted-pricing endpoint

Core Spend

Method	Path	Purpose
`POST`	`/v1/ssar/fetch`	Main governed request endpoint
`GET`	`/v1/budget/status`	Budget and mandate snapshot
`GET`	`/v1/decisions/:id/explain`	Decision forensics
`GET`	`/v1/receipts/:id`	Receipt lookup
`POST`	`/v1/approvals/:id/consume`	Return an approval token for a retry
`GET`	`/v1/approvals/:id/status`	Approval status, expiry, and token state

Operator & Admin

Method	Path	Purpose
`GET`	`/v1/me`	Introspect the auth context (org + signing mode + scopes)
`GET`	`/v1/api-keys`	List API keys for an organization
`POST`	`/v1/api-keys`	Mint an org-wide or wallet-scoped API key
`POST`	`/v1/orgs/bootstrap`	Browser-session org bootstrap
`POST`	`/v1/orgs/bootstrap/browser`	Browser-signing bootstrap path
`GET`	`/v1/orgs/:id/readiness`	Org-scoped readiness view
`GET`	`/v1/orgs/:id/workforce`	Workforce read model
`GET`	`/v1/orgs/:id/vault`	Treasury overview
`GET`	`/v1/wallets`	List wallets in the caller’s organization
`GET`	`/v1/wallets/:wallet_id`	Wallet details (includes deposit and allocation info)
`POST`	`/v1/orgs/:id/transfers/fund`	Allocate from vault to agent pocket (server-signed orgs)
`POST`	`/v1/wallets/:wallet_id/fund`	Allocate from vault to a specific pocket (convenience alias)
`POST`	`/v1/orgs/:id/transfers/sweep`	Sweep pocket back to vault
`POST`	`/v1/orgs/:id/reconcile`	Treasury reconciliation
`POST`	`/v1/agents`	Create agent wallet + mandate
`GET`	`/v1/offers`	Reduced operator discovery list of offers
`GET`	`/v1/ledger`	Org or wallet ledger view
`GET`	`/v1/mandates`	Mandates for the caller’s organization
`GET`	`/v1/approvals`	Approval list for the caller’s organization

Providers

Method	Path	Purpose
`GET`	`/v1/providers`	List providers
`PUT`	`/v1/providers/:id`	Update provider metadata
`POST`	`/v1/providers/seed`	Seed registry from bundled data
`POST`	`/v1/providers/sync`	Run provider sync
`POST`	`/v1/providers/health-check`	Run health checks

Provider Search

Method	Path	Purpose
`POST`	`/v1/provider-search`	Wallet-aware provider search
`GET`	`/v1/provider-search/offers/:offer_id`	Inspect a discovered offer
`POST`	`/v1/provider-search/offers/:offer_id/quote`	Quote a discovered offer
`POST`	`/v1/provider-search/offers/:offer_id/test-buy`	Buyer-journey delegated test buy
`POST`	`/v1/provider-search/feedback`	Internal feedback ingest

Discovery

Method	Path	Purpose
`GET`	`/v1/discovery/resources`	Public discovery feed (no auth)

Public Paid Gateway

Method	Path	Purpose
`GET / POST`	`/o/:slug`	Public paid URL for managed_gateway and hosted_asset offers. Serves 402 challenge when unpaid, forwards to origin / serves file after settlement. See Managed Gateway.

MCP over HTTP

Method	Path	Purpose
`GET / POST / DELETE`	`/v1/mcp`	Runtime MCP over Streamable HTTP. Exposes the current 17-tool runtime surface, including provider-search tools.
`GET / POST / DELETE`	`/v1/wallets/:wallet_id/mcp`	Legacy runtime MCP path with wallet in the URL
`GET / POST / DELETE`	`/v1/operator/mcp`	Operator MCP over Streamable HTTP

/v1/mcp is wallet-scoped. An org-wide tenant key with no wallet binding receives a JSON-RPC-framed WALLET_BINDING_REQUIRED error. Static operator-key fallback is demo-only; live HTTP runtime clients should use wallet-bound tenant keys.

Workers

Method	Path	Purpose
`POST`	`/v1/webhooks/dispatch`	Run webhook dispatch batch
`POST`	`/v1/approvals/expire`	Expire stale approvals
`POST`	`/v1/transactions/confirm`	Run confirmation worker
`GET`	`/v1/metrics`	Aggregate operational metrics

Settlements

Method	Path	Purpose
`GET`	`/v1/settlements/:recording_key`	Look up a settlement journal entry by its recording key or journal UUID. Any authed caller; org-scoped by the journal’s wallet.

Operator (operator-only)

These REST routes require the static operator key (AXON_DECISION_API_KEY). The separate /v1/operator/mcp MCP entrypoint also accepts org-wide tenant keys.

Method	Path	Purpose
`POST`	`/v1/operator/pause`	Activate the global pause
`POST`	`/v1/operator/resume`	Clear the global pause
`GET`	`/v1/operator/status`	Global pause + worker heartbeats + repair queue summary
`GET`	`/v1/operator/launch-gate`	Run all data-integrity audits; returns `200` when ready-to-launch, `503` otherwise
`POST`	`/v1/operator/emergency-stop`	Stop a pocket, department, or organization
`POST`	`/v1/operator/trigger/repair-queue`	One-shot run of the repair queue worker

Repair (operator-only)

Dead-letter replay and manual reconciliation endpoints. All routes require the operator key.

Method	Path	Purpose
`GET`	`/v1/repair/webhooks/dead-letter`	List webhook events in dead-letter
`POST`	`/v1/repair/webhooks/:id/replay`	Requeue a single dead-letter webhook
`POST`	`/v1/repair/webhooks/replay-all`	Requeue every dead-letter webhook
`GET`	`/v1/repair/queue`	List `repair_queue` items (supports `status` and `domain` filters)
`POST`	`/v1/repair/queue/:id/retry`	Retry a single dead-letter or stuck-claimed repair item
`POST`	`/v1/repair/queue/retry-all`	Retry every dead-letter or stuck-claimed repair item (optional `domain` filter)
`GET`	`/v1/repair/journals/incomplete`	List settlement journals that never produced an earning
`POST`	`/v1/repair/journals/:id/reconcile`	Manually recover the earning for an incomplete journal

Request body limit is 256kb unless a route installs its own handler, such as file upload or the paid gateway.

Overview

Onboarding

Core Spend

Approvals

Organizations

Treasury

Providers

Discovery

Workers & Observability

MCP Tools

Reference

API Overview

Authentication

Error Format

HTTP Status Codes

Surface split

Endpoint Summary

Public

Core Spend

Operator & Admin

Providers

Provider Search

Discovery

Public Paid Gateway

MCP over HTTP

Workers

Settlements

Operator (operator-only)

Repair (operator-only)

​Authentication

​Error Format

​HTTP Status Codes

​Surface split

​Endpoint Summary

​Public

​Core Spend

​Operator & Admin

​Providers

​Provider Search

​Discovery

​Public Paid Gateway

​MCP over HTTP

​Workers

​Settlements

​Operator (operator-only)

​Repair (operator-only)

Authentication

Error Format

HTTP Status Codes

Surface split

Endpoint Summary

Public

Core Spend

Operator & Admin

Providers

Provider Search

Discovery

Public Paid Gateway

MCP over HTTP

Workers

Settlements

Operator (operator-only)

Repair (operator-only)