# PumaClaw API Documentation

PumaClaw v1 exposes a public discovery surface and an early-access **control plane** for mobile operators.

## Discovery endpoints

| Endpoint | Media type | Purpose |
| --- | --- | --- |
| `/.well-known/api-catalog` | `application/linkset+json` | API catalog with service description, documentation, and status links. |
| `/.well-known/openapi.json` | `application/vnd.oai.openapi+json` | OpenAPI description for discovery and control-plane endpoints. |
| `/health.json` | `application/json` | Public site health metadata. |
| `/robots.txt` | `text/plain` | Crawl policy, AI crawler rules, content signals, and sitemap reference. |
| `/sitemap.xml` | `application/xml` | Canonical sitemap for public pages. |
| `/docs/architecture.md` | `text/markdown` | v1 system architecture. |

## Control plane (`/api/v1`)

Operator console and integrators use these routes. On Cloudflare Pages they are served by Functions. On a static preview host the `/app` console falls back to an equivalent local demo store.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/v1/health` | Control-plane readiness |
| `GET` | `/api/v1/status` | Dashboard snapshot (sessions, approvals, lockout, metrics) |
| `GET` | `/api/v1/sessions` | List sessions |
| `POST` | `/api/v1/sessions` | Create session |
| `POST` | `/api/v1/sessions/{id}/start` | Start session |
| `POST` | `/api/v1/sessions/{id}/pause` | Pause session |
| `POST` | `/api/v1/sessions/{id}/stop` | Stop session |
| `GET` | `/api/v1/approvals` | List pending approvals (`?includeResolved=1` for history) |
| `POST` | `/api/v1/approvals/{id}/approve` | Approve request |
| `POST` | `/api/v1/approvals/{id}/deny` | Deny request |
| `GET` | `/api/v1/devices` | List devices |
| `POST` | `/api/v1/devices/{id}/trust` | Trust device |
| `POST` | `/api/v1/devices/{id}/revoke` | Revoke device |
| `GET` | `/api/v1/audit` | Audit events |
| `POST` | `/api/v1/lockout` | Body `{ "engaged": true\|false, "reason?": string }` |
| `GET` | `/api/v1/gateway` | Gateway adapter description |
| `POST` | `/api/v1/gateway` | Body `{ "gatewayUrl": string }` save live target |
| `POST` | `/api/v1/demo/tick` | Advance demo metrics |
| `POST` | `/api/v1/demo/approval` | Queue a simulated inbound approval |
| `POST` | `/api/v1/demo/reset` | Reset demo world |

### Headers

| Header | Required | Purpose |
| --- | --- | --- |
| `X-PumaClaw-Operator` | recommended | Operator identity (`operator:demo` in the console) |
| `X-PumaClaw-Confirm` | for high-risk writes | Must be `1` for medium+ risk mutations |
| `X-PumaClaw-Client` | optional | Client identifier |

### Risk policy

High-risk and critical actions (approvals, stop, device revoke, lockout) require confirmation. While lockout is engaged, only reads plus lockout clear remain available.

### Example

```http
GET /api/v1/status HTTP/1.1
Accept: application/json
X-PumaClaw-Operator: operator:demo
```

```http
POST /api/v1/approvals/appr_net_01/approve HTTP/1.1
Accept: application/json
X-PumaClaw-Operator: operator:demo
X-PumaClaw-Confirm: 1
```

## Operator console

Mobile PWA: [https://pumaclaw.com/app/](https://pumaclaw.com/app/)

## Auth notes

OAuth discovery metadata advertises scopes:

- `pumaclaw.discovery:read`
- `pumaclaw.sessions:read`
- `pumaclaw.sessions:write`

Protected production token exchange remains early-access. Email Claw@PumaAI.com for access. Demo mode uses operator headers without bearer tokens.