Endpoint reference

The public REST surface lives under /api/agent/v1 on the local Whet Desktop instance (or your Team / Enterprise host). This is the same API the CLI and the MCP server consume.

Auth: Authorization: Bearer <agent-token> (the 64-char hex token Whet generated on first launch — see Authentication).

If you also need to drive the drafting canvas (sessions) or workspace analytics (dashboards), those operations are reachable via the MCP server (/api/mcp). Sessions also expose a few REST endpoints under /api/sessions/* for server-side bridges — see Sessions.

Conventions

• All paths are relative to http://localhost:7891/api/agent/v1 (local Whet Desktop) or https://your-team.whet.so/api/agent/v1 (Team / Enterprise).
• All requests must include Authorization: Bearer <agent-token>.
• Mutating endpoints accept an idempotency_key in the body (16–128 chars). Replaying with the same key returns the same run/result. See Idempotency.
• IDs are opaque — see whet reference · ID shape.
• Errors share the shape { error: { code, message, suggested_action?, suggested_endpoint? } }. See Errors.

Pipelines

Method	Path	Description
GET	/pipelines/{id}	Fetch a single pipeline.
POST	/pipelines/from-intent	Create-or-resume from intent. Body: { handle, intent, tone?, idempotency_key }. Returns { pipeline_id, run_id }.
GET	/pipelines/{id}/diagnose	Structured health report. Each issue carries suggested_action and suggested_endpoint.
GET	/pipelines/{id}/inbox	Items awaiting agent attention (drafts in review, sources without artifacts, flagged anomalies).
GET	/pipelines/{id}/posts	Paginated source posts with engagement metrics. Query: cursor, limit (1–100), has_artifact (bool).

Posts

Method	Path	Description
POST	/posts/{id}/draft	Start a draft from a source post. Body: { style_reference?, parent_artifact_id?, idempotency_key }. Returns { run_id }.

Artifacts

Method	Path	Description
GET	/artifacts/{id}	Fetch artifact text, state, genealogy.
POST	/artifacts/{id}/publish	Transition review/ready → published. Body: { idempotency_key }.

Connected accounts

Method	Path	Description
POST	/accounts/connect	Add or rotate a platform account credential. Body: { platform, handle, auth_material, secondary_auth?, proxy_url?, idempotency_key }. The probe runs synchronously.

URL fetch

Method	Path	Description
POST	/fetch	Fetch and structure a public HTTPS URL. Body: { url, mode?, intent?, schema_id? }. mode: markdown | css | llm | auto (default).

Sessions (workbench REST bridges)

These three endpoints live on whet-app (not under /api/agent/v1) and mirror the MCP session tools for callers that prefer REST over MCP transport. See Sessions for the full model.

Method	Path	Description
GET	/api/sessions/activity	Latest activity rows across the org's sessions. Query: ?limit (1–100, default 20).
POST	/api/sessions/{sessionId}/items	Server-side session_add_item.
POST	/api/sessions/{sessionId}/variants/{variantId}/regenerate	Trigger a variant regeneration (appends a variant_round).
POST	/api/sessions/sources/{id}/refresh	Async refresh of an upstream source.

Webhooks (inbound to whet-app)

whet-app exposes two webhook receivers. They are not for external consumers — they receive events from the backend and the optional ingestion monitor:

Method	Path	Auth	Description
POST	/api/webhooks/backend	HMAC via WEBHOOK_SIGNING_SECRET	Backend events (pipeline runs, artifacts, sessions).
POST	/api/webhooks/scraper-monitor	HMAC via PICKO_SCRAPER_SIGNING_SECRET	Ingestion-monitor diff events (the route path retains the legacy name pending the U10c rename). Returns 503 when no monitor is configured.

If you want to consume backend events from an external service, the recommended path is the SSE stream below.

Streaming

Method	Path	Description
GET	/api/stream	Server-Sent Events feed of backend events scoped to the active org. text/event-stream; heartbeat every 15s. Query: ?events=<comma-separated> filter for event types.

Auth: same Bearer agent token. Reconnect on EventSource.onerror with a backoff.

What is not exposed (commonly searched)

• There is no public-API HMAC-signed REST surface (/api/v1/whet/* is not a real path).
• There are no pk_live_* / pk_test_* keys. The agent token is the single public credential.
• There are no POST /webhook_endpoints / POST /api_keys admin routes. Webhook subscriptions and API keys are not managed via the public API today.
• Refinement is reached via MCP (refine_post prompt) or, internally, via the backend route. There is no /refinements public endpoint.

For roadmap items (multi-key auth, public webhook subscriptions, scoped admin), open an issue.