Skip to main content

Quickstart — REST API

Whet has one public REST surface today: the Agent API at /api/agent/v1 on whet-app. The CLI and the MCP server are both clients of it; you can be too.

SurfaceEndpointAuthWhat for
Agent API/api/agent/v1/*Authorization: Bearer <agent-token>Pipelines, drafts, inbox, publish, platform credentials, URL fetch.
MCP/api/mcpSame BearerSessions, dashboards, prompts, resources — driven through MCP transport, not REST.
SSE stream/api/streamSame BearerReceive backend events as they fire.
Workbench UI/better-auth sessionFull operator UI.

This page covers the Agent API. For sessions/dashboards via MCP, see MCP · what it is.

If you are only going to use the workbench UI, you do not need this section — the UI already authenticates every request for you.

Before you start​

You need:

  • Whet Desktop running locally (reachable at http://localhost:7891), or a Team / Enterprise host reachable over HTTPS.
  • An agent token — a 64-character hex string with no prefix. Whet generates it on first launch and persists it in your OS keychain. Read it from Settings → Agent tokens in the workbench, or copy it from ~/.whet/config.json after running whet auth login.

That's it — no HMAC, no signing secret, no clock-skew handling.

Steps​

1. Set the base URL​

export WHET_BASE_URL="http://localhost:7891/api/agent/v1"   # or https://your-team.whet.so/api/agent/v1
export WHET_TOKEN="7a3f4b2c…e2d8"   # 64-char hex

2. Smoke-test with GET /pipelines/{id}​

If you don't have a pipeline id yet, fetch one from the workbench UI or via whet pipelines new. Then:

curl -s "$WHET_BASE_URL/pipelines/$PIPELINE_ID" \
  -H "Authorization: Bearer $WHET_TOKEN"

A 200 with JSON means you're in. A 401 means the token is invalid or revoked.

3. Create a pipeline from intent​

The classic agent flow — give a handle + intent, get a pipeline back. The endpoint is idempotent: replaying with the same idempotency_key resumes the same pipeline.

curl -X POST "$WHET_BASE_URL/pipelines/from-intent" \
  -H "Authorization: Bearer $WHET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "growth_dr",
    "intent": "Track for analytical drafts, daily.",
    "tone": "analytical",
    "idempotency_key": "01HXAMPLE...REPLAYABLE"
  }'

Response shape (illustrative):

{
  "pipeline_id": "pp_a1b2c3...",
  "run_id": "run_482"
}

4. Handle the async response​

Long operations (create-from-intent, draft, fetch, publish) return immediately with a run_id. Three ways to know when the run finished, in order of preference:

  1. SSE stream (recommended). GET /api/stream keeps a text/event-stream connection open and emits the events you care about (pipeline.ready, riff.ready, decode.ready, etc.). Same Bearer token. See Webhooks.
  2. Poll GET /pipelines/{id}/inbox or GET /pipelines/{id} with exponential backoff. Stateless, simpler, worse latency.
  3. Inbound webhook on your side: configure your own ingestion endpoint and have whet-app push to it via /api/webhooks/backend — but this requires you to run on the same trust boundary, since the public API doesn't yet manage external subscriptions.

5. Idempotency​

Every mutating endpoint accepts idempotency_key (16–128 chars) in the body, not as a header. Replays with the same key return the same run, never a new one. See Idempotency.

const idempotencyKey = crypto.randomUUID().replaceAll("-", "");
// → 32-char hex, well within the 16–128 range.

What about pk_live_* / pk_test_*?​

If you've seen mentions of pk_live_… keys, HMAC signatures and a /api/v1/whet prefix, that surface does not exist in the current code. There's one auth scheme (Bearer agent token) and one surface (/api/agent/v1).

The HMAC machinery (WEBHOOK_SIGNING_SECRET) is only used for inbound webhook deliveries on Basic / Pro — see Webhooks · HMAC verification. It is not part of the public Agent API.

Next step​