> ## 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.

# REST API Integration

> Direct HTTP integration with the Decision daemon

For service-to-service integrations, you can call the Decision API directly without MCP or OpenClaw. The public hosted base URL is `https://api.axon402.com`; local development typically uses `http://127.0.0.1:3030`.

## Setup

1. Choose your base URL:

```bash theme={null}
export AXON_API_URL=https://api.axon402.com
```

For local development instead:

```bash theme={null}
cd axon-402-mcp
npm run build
npm run start:decision-api
export AXON_API_URL=http://127.0.0.1:3030
```

2. Authenticate with a bearer token. AXON recognises two key types for REST integrations:

```http theme={null}
Authorization: Bearer <KEY>
Content-Type: application/json
```

* **Operator key** — the static `AXON_DECISION_API_KEY`. Full trust; required for `/v1/operator/*`, `/v1/repair/*`, provider registry mutations, worker triggers, and global metrics.
* **Tenant API key** (`axon_sk_…`) — scoped to an organization (and optionally to a single wallet). Can be minted via `POST /v1/api-keys`. Wallet-bound keys are the runtime credential shape for `/v1/ssar/fetch`, `/v1/budget/status`, `/v1/approvals/*`, and `/v1/receipts/*`. Org-wide keys (no `wallet_id`) are the operator-surface credential shape for seller and control-plane routes such as `/v1/services/*`.

Service-to-service integrations should almost always use a **tenant key** so access is scoped to the caller's org. Reserve the operator key for the on-call runbook.

> [!NOTE]
>
> Wallet-bound runtime keys are rejected on seller/control-plane routes
> guarded by `assertOperatorSurface(...)`. Those calls return
> `403 TOOL_NOT_AVAILABLE_IN_RUNTIME_SURFACE`.

> [!NOTE]
>
> `POST /v1/orgs/bootstrap/browser` is gated by the server-side `AXON_HOSTED_BROWSER_BOOTSTRAP_DISABLED` kill switch. When `true`, hosted deployments reject the request regardless of credentials.

## Minimal Integration

### Make a governed request

```bash theme={null}
curl -X POST "$AXON_API_URL/v1/ssar/fetch" \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "intent": "Fetch market data for analysis",
    "task_id": "task-001",
    "wallet_id": "<POCKET_WALLET_ID>",
    "idempotency_key": "unique-request-key"
  }'
```

Direct REST calls do not inject `wallet_id` from a wallet-scoped API
key. Send `wallet_id` explicitly unless the daemon's default
`AGENT_WALLET_ID` is already pinned to the wallet you intend to use.
If you bootstrapped with `npx @axon402/init`, read the correct
`wallet_id` from `~/.axon/config.json`.

### Check budget

```bash theme={null}
curl -s \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/budget/status?wallet_id=<WALLET_ID>"
```

Wallet-scoped tenant keys may omit `wallet_id` on this route; org-wide
keys must provide it.

### Handle approval flow

```bash theme={null}
# 1. Original request returns APPROVAL_REQUIRED with approval_request_id

# 2. Check approval status
curl -s \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/approvals/$APPROVAL_ID/status"

# 3. After operator approves, consume the token
curl -X POST \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  "$AXON_API_URL/v1/approvals/$APPROVAL_ID/consume"

# 4. Retry with approval token (same idempotency_key)
curl -X POST "$AXON_API_URL/v1/ssar/fetch" \
  -H "Authorization: Bearer $AXON_RUNTIME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/data",
    "intent": "Fetch market data for analysis",
    "task_id": "task-001",
    "wallet_id": "<POCKET_WALLET_ID>",
    "idempotency_key": "unique-request-key",
    "approval_token": "<APPROVAL_TOKEN>"
  }'
```

## Health Checks

```bash theme={null}
# Liveness
curl "$AXON_API_URL/v1/health"

# Readiness (checks DB, wallet, mandate, workers)
curl "$AXON_API_URL/v1/ready"
```

Only proceed if `/ready` returns `200`. A green `/health` alone is not sufficient.

## Operator-only endpoints

These endpoints require the static operator key. They are intended for AXON on-call operators, not for customer application code or normal tenant integrations.

| Group | Paths | Purpose |
| :- | :- | :- |
| Global controls | `POST /v1/operator/pause`, `/v1/operator/resume`, `GET /v1/operator/status`, `POST /v1/operator/emergency-stop` | Pause/resume traffic, inspect worker health, emergency-stop a pocket/department/org. |
| Launch gate | `GET /v1/operator/launch-gate` | Run data-integrity audits; returns `503` if not ready. |
| Manual trigger | `POST /v1/operator/trigger/repair-queue` | One-shot repair-queue run for game-day scenarios. |
| Webhook repair | `GET /v1/repair/webhooks/dead-letter`, `POST /v1/repair/webhooks/:id/replay`, `/v1/repair/webhooks/replay-all` | Inspect and requeue dead-letter webhooks. |
| Repair queue | `GET /v1/repair/queue`, `POST /v1/repair/queue/:id/retry`, `/v1/repair/queue/retry-all` | Inspect and retry dead-letter or stuck `repair_queue` items. |
| Journal repair | `GET /v1/repair/journals/incomplete`, `POST /v1/repair/journals/:id/reconcile` | Manually recover an earning from a settlement journal that never completed end-to-end. |

See the full [API Reference](https://docs.axon402.com/docs/api-reference/overview.md) for all endpoints.


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