# OSz Capability & Console API — building on the governed surface

The console API is the session-authenticated surface humans (and apps built
for humans) use. Sessions come from `POST /auth/login` (email + password →
httpOnly cookie). All state-changing calls require the `X-Requested-With`
header (CSRF). Roles: `USER` (sovereign over their own requests, agents,
capabilities) and `ADMIN` (everything, incl. platform decisions).

## Ask / answer

| Endpoint | What |
|---|---|
| `POST /api/console/route` `{q}` | The router: one utterance → the right destination. Single questions answer instantly (disclosure). Task-shaped input (conjunctions, "do:") is planned structurally and becomes an owner-scope proposal — the requester's approval popup fires. Response `type` ∈ `weather · directions · wiki · define · ask · tool · websearch · reasoning · task_route · orchestration_pending · catalog · hint` |
| `POST /api/console/compose` `{q}` | Multi-source synthesis: OSz domain knowledge + Wikipedia + governed web search gathered in parallel; the gated LLM edge composes ONE answer citing `[OSz]/[Wikipedia]/[Web n]` only from provided sources |
| `GET /api/console/ask?q=` | Raw domain intelligence: matches, live counts, hypotheses, insights, forecasts |
| `GET /api/console/orchestrations/:proposalId` | Result of an approved orchestrated task (owner or admin) |

## Capabilities (external tools under the constitution)

- `GET /api/console/capabilities` — everything callable: 12 built-ins
  (weather, directions, wikipedia, websearch, reasoning, time, currency,
  crypto, dictionary, holidays, country, airquality — all disclosure-class)
  plus every connected MCP server.
- `POST /api/console/capability/call` `{connection, tool, args}` —
  disclosure tools return `{mode:"disclosure", result}` instantly (receipted);
  action tools return `{mode:"action_pending", proposalId}` and wait at the
  Gate.
- `GET /api/console/catalog?q=` — search the ingested **planetary MCP
  registry** (19k+ servers) in plain words; results ranked connectable-first.
- `POST /api/console/connections/add` `{name, endpoint}` — connect any MCP
  server: validated by a real handshake (initialize + tools/list) before
  registration; receipted; **all tools action-class by default** until
  read-only tools are allowlisted. `/connections/remove {name}` disables
  (owner or admin), instantly.

## Agents (inbound)

- `POST /api/console/agents/connect` `{name, protocol?}` → owner-bound
  credential (plaintext once), agent id `owner.name`, issuance receipted.
- `GET /api/console/agents/mine` — your fleet (admins: all, with owners):
  status, key prefix, last seen, request count.
- `POST /api/console/agents/revoke` `{keyId}` — immediate, receipted.

## Tasks & decisions

- `POST /api/console/task` `{domain, description, agent?}` — a governed
  task proposal (owner-scope, 100¢ compute cap). With `agent`, execution
  routes to YOUR connected agent via the protocol task feed after approval.
- `GET /api/console/queue` (admin) — pending proposals with summaries.
- `POST /api/console/decide` `{proposalId, decision: approved|denied,
  reason(≥8 chars)}` — non-admins may decide only their own owner-scope
  proposals; every decision receipts under the decider's email and executes
  on approval. `/decide-category` (admin) batches one intent type, one
  transaction per proposal.
- `GET /api/console/events` — SSE stream: `proposal` events (admins: all;
  users: their own owner-scope), `proposal_batch` for bursts, and `notice`
  events (OSz messaging its human — e.g. `authorization_needed` when a
  capability declines with an access challenge). Notices deliver exactly
  once.

## Read surfaces

`GET /api/console/stats` (public aggregates; 15s cache; stall-proof) ·
`/receipts` · `/mine` (Qbitz, transactions, decisions, agents) · `/me`.

## The two rules that never bend

1. **Disclosure is instant; action asks a human.** The classification is
   server-side and structural — clients cannot opt out.
2. **Everything is receipted.** If you built it on this API, its history is
   replayable — that's the feature you inherit for free.