The CRHQ Platform API: build your own product on the agent engine

CRHQ is now a headless platform. The full agent engine, sessions, live chat, delegation, scheduling, skills and cost tracking, is available over a documented HTTP API. You can build your own product, dashboard, or an entirely different user experience on top of it: your pages, your database for your own concepts, your interface. CRHQ runs the agents, you own the experience.

Where to start

One URL gives you the whole surface:

GET https://<your-satellite>/api/openapi.json

That is the complete, machine-readable API contract. It is public, needs no key, and is the document you code and test against. Point your editor, your codegen, or your agent at it and you have the full map.

Auth: scoped API keys

Ask your satellite operator for an API key with exactly the permissions your app needs, then send it as X-Api-Key on every request. A key missing a permission gets a clear 403 naming the scope it lacks, so nothing fails silently.

Sessions with your own identity and secrets

A session is a running agent. You can give each one its own persona and its own secrets at creation, without touching a stored agent:

POST /api/sessions
{ "agent": "my-runner",
  "model": "haiku",
  "instructions": "…your persona…",   // replaces the agent's instructions
                                       // for THIS session only
  "secrets": { "MY_API_TOKEN": "…" }   // encrypted at rest, injected as env
}                                      // vars only, never in transcripts

POST /api/sessions/{id}/message   { "content": "do the thing" }
GET  /api/sessions                ?agent=&status=&mine=true
GET  /api/sessions/{id}           transcript, metadata, queue, artifacts

This is the disposable-identity pattern: keep one blank runner agent, then give each session its own instructions and secrets. Sessions are cheap, the identity is yours.

Live streaming

Watch agents work in real time over server-sent events, one session or all of them at once:

GET /api/sessions/{id}/stream
  events: turn.started, message.delta, tool.started, tool.finished,
          turn.completed, session.idle, session.error
  reconnect with Last-Event-ID for lossless replay; if you were gone too
  long you get an explicit gap event, so you know to refetch and resume

GET /api/events/stream          ?sessions=a,b&agents=x
  every session at once, for boards and dashboards

The streams are designed for real interfaces: reconnection is lossless when it can be, and honest about it when it cannot.

Webhooks: get pushed, never poll

POST /api/webhooks
{ "url": "https://your-app/hooks", "secret": "…at least 16 chars…",
  "events": ["session.completed", "session.needs_input",
             "session.error", "delegation.status_changed",
             "job.run_completed"] }

Every delivery is HMAC-signed in an X-CRHQ-Signature header, carries an X-CRHQ-Delivery dedup id, and retries for up to 6 hours if your endpoint is down. Deliveries survive satellite restarts, and you can inspect or replay them from the API while building.

Delegations, jobs, usage, credentials

POST /api/delegations   {agent, task, parentSessionId}
GET  /api/jobs · POST /api/jobs · POST /api/jobs/{id}/run-now
GET  /api/usage?groupBy=agent|session|day|model
     tokens and cost per slice, ready for client-facing billing
PUT  /api/credentials/{slug}/{account}   create or silently rotate

The credential vault is one-way by design. Your app deposits and rotates tokens, agents' skills use them under grants, and no API call ever returns secret material.

The stability promise

This is a contract you can build a business on, not a moving target:

• Versioned. Additive changes bump the minor version. Breaking changes bump the major version, land in the changelog, and honour a 90-day deprecation window. A CI guard makes it impossible for the deployed API and the published contract to disagree.
• Uniform. Everything lives under clean resource paths: /api/sessions, /api/agents, /api/skills, /api/jobs. Older spellings keep working, but new code should use the canonical ones.
• Safe by default. Everything your app receives, streams and transcripts alike, passes the platform's secret-redaction layer. Webhook targets on private networks require operator registration, and per-key connection limits stop one app from starving the others.

A minimal custom front-end

1. GET  /api/openapi.json                      know the surface
2. POST /api/sessions {agent, instructions}    your identity
3. POST /api/sessions/{id}/message             start work
4. GET  /api/sessions/{id}/stream              render it live
5. POST /api/webhooks {session.completed}       react when it finishes
6. GET  /api/sessions?mine=true                your app's home screen
7. GET  /api/usage?groupBy=session             show what it cost

Store your own concepts, boards, workspaces, whatever your product invents, in your own database, and reference sessions by id. CRHQ stays the engine. The experience is yours.

Availability