Saltar al contenido principal

Quickstart — REST API

Whet tiene una superficie REST pública hoy: el Agent API en /api/agent/v1 sobre whet-app. El CLI y el MCP server son ambos clientes; vos también podés serlo.

SuperficieEndpointAuthPara qué
Agent API/api/agent/v1/*Authorization: Bearer <agent-token>Pipelines, drafts, inbox, publish, cookies de X, scrape.
MCP/api/mcpMismo BearerSessions, dashboards, prompts, resources — manejado por el transport MCP, no REST.
SSE stream/api/streamMismo BearerRecibí eventos del backend a medida que ocurren.
UI del workbench/Sesión de better-authUI completa del operador.

Esta página cubre el Agent API. Para sessions/dashboards vía MCP, ver MCP · qué es.

Si solo vas a usar la UI del workbench, no necesitás esta sección — la UI ya autentica cada request por vos.

Antes de empezar​

Necesitás:

  • Una instancia Whet corriendo accesible vía HTTPS (o http://localhost para dev).
  • Un agent token — un string hex de 64 caracteres sin prefijo. bench-up.sh lo genera al primer boot y lo imprime en el banner. También lo podés leer desde ~/.whet/config.json después de correr whet auth login.

Eso es todo — sin HMAC, sin signing secret, sin manejo de clock-skew.

Pasos​

1. Setear la base URL​

export WHET_BASE_URL="https://your.vps/api/agent/v1"
export WHET_TOKEN="7a3f4b2c…e2d8"   # hex de 64 chars

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

Si todavía no tenés un pipeline id, traé uno desde la UI del workbench o vía whet pipelines new. Después:

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

Un 200 con JSON significa que estás adentro. Un 401 significa que el token es inválido o fue revocado.

3. Crear un pipeline desde intent​

El flujo agente clásico — pasás handle + intent y obtenés un pipeline. El endpoint es idempotente: repetir con la misma idempotency_key resume el mismo 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"
  }'

Shape de respuesta (ilustrativo):

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

4. Manejar la respuesta async​

Las operaciones largas (create-from-intent, draft, scrape, publish) devuelven inmediatamente con un run_id. Tres formas de saber cuándo terminó el run, en orden de preferencia:

  1. SSE stream (recomendado). GET /api/stream mantiene una conexión text/event-stream abierta y emite los eventos que te importan (pipeline.ready, riff.ready, decode.ready, etc.). Mismo Bearer token. Ver Webhooks.
  2. Poll de GET /pipelines/{id}/inbox o GET /pipelines/{id} con backoff exponencial. Stateless, más simple, peor latencia.
  3. Webhook entrante del lado tuyo: configurás tu propio endpoint de ingest y hacés que whet-app empuje por /api/webhooks/backend — pero esto requiere correr en el mismo trust boundary, porque el API público todavía no maneja suscripciones externas.

5. Idempotencia​

Cada endpoint mutativo acepta idempotency_key (16–128 chars) en el body, no como header. Repetir con la misma key devuelve el mismo run, nunca uno nuevo. Ver Idempotencia.

const idempotencyKey = crypto.randomUUID().replaceAll("-", "");
// → hex de 32 chars, holgadamente dentro del rango 16–128.

¿Y los pk_live_* / pk_test_*?​

Si viste menciones de keys pk_live_…, firmas HMAC y prefijo /api/v1/whet, esa superficie no existe en el código actual. Hay un solo esquema de auth (Bearer agent token) y una sola superficie (/api/agent/v1).

La maquinaria HMAC (INTERNAL_HMAC_SECRET, WEBHOOK_SIGNING_SECRET) sí existe, pero es para canales internos — whet-app ↔ backend y webhooks backend → whet-app. No está expuesta a clientes públicos.

Siguiente paso​