> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axon402.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Decision daemon REST API reference

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**

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`)

```http theme={null}
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`.

**Tenant API key**

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.

```http theme={null}
Authorization: Bearer axon_sk_<...>
```

**Supabase session**

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:

```json theme={null}
{
  "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](https://docs.axon402.com/docs/concepts/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 |

> [!NOTE]
>
> Request body limit is `256kb` unless a route installs its own handler, such as file upload or the paid gateway.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.