Referencia de endpoints

La superficie REST pública vive bajo /api/agent/v1 sobre whet-app. Es el mismo API que consumen el CLI y el MCP server.

Auth: Authorization: Bearer <agent-token> (el token hex de 64 chars generado por bench-up.sh — ver Autenticación).

El backend Bun en BACKEND_BASE_URL es interno — solo whet-app lo alcanza vía canal HMAC. No es parte del API público y sus rutas no se documentan acá.

Si además necesitás manejar el canvas de drafting (sessions) o las analytics del workspace (dashboards), esas operaciones están disponibles vía el MCP server (/api/mcp). Las sessions también exponen algunos endpoints REST bajo /api/sessions/* para bridges server-side — ver Sessions.

Convenciones

• Todos los paths son relativos a https://your.vps/api/agent/v1.
• Todos los requests deben incluir Authorization: Bearer <agent-token>.
• Los endpoints mutativos aceptan idempotency_key en el body (16–128 chars). Repetir con la misma key devuelve el mismo run/resultado. Ver Idempotencia.
• Los IDs son opacos — ver referencia de whet · forma de los IDs.
• Los errores comparten el shape { error: { code, message, suggested_action?, suggested_endpoint? } }. Ver Errores.

Pipelines

Método	Path	Descripción
GET	/pipelines/{id}	Trae un pipeline.
POST	/pipelines/from-intent	Create-or-resume desde intent. Body: { handle, intent, tone?, idempotency_key }. Devuelve { pipeline_id, run_id }.
GET	/pipelines/{id}/diagnose	Reporte estructurado de salud. Cada issue lleva suggested_action y suggested_endpoint.
GET	/pipelines/{id}/inbox	Items esperando atención del agente (drafts en review, sources sin artifacts, anomalías flaggeadas).
GET	/pipelines/{id}/posts	Source posts paginados con métricas de engagement. Query: cursor, limit (1–100), has_artifact (bool).

Posts

Método	Path	Descripción
POST	/posts/{id}/draft	Inicia un draft desde un source post. Body: { style_reference?, parent_artifact_id?, idempotency_key }. Devuelve { run_id }.

Artifacts

Método	Path	Descripción
GET	/artifacts/{id}	Trae texto, estado y genealogía del artifact.
POST	/artifacts/{id}/publish	Transición review/ready → published. Body: { idempotency_key }.

X accounts

Método	Path	Descripción
POST	/x-accounts/connect	Agrega o rota una credencial de X. Body: { handle, auth_token, ct0?, proxy_url?, idempotency_key }. El probe corre sincrónicamente.

Scrape

Método	Path	Descripción
POST	/scrape	Fetch + estructurado de una URL HTTPS pública. Body: { url, mode?, intent?, schema_id? }. mode: markdown | css | llm | auto (default).

Sessions (bridges REST del workbench)

Estos tres endpoints viven en whet-app (no bajo /api/agent/v1) y espejan las tools MCP de sessions para callers que prefieren REST sobre transport MCP. Ver Sessions para el modelo completo.

Método	Path	Descripción
GET	/api/sessions/activity	Últimos rows de activity en las sessions de la org. Query: ?limit (1–100, default 20).
POST	/api/sessions/{sessionId}/items	session_add_item server-side.
POST	/api/sessions/{sessionId}/variants/{variantId}/regenerate	Dispara una regeneración de variante (appendea un variant_round).
POST	/api/sessions/sources/{id}/refresh	Refresh async de una source upstream.

Webhooks (entrantes a whet-app)

whet-app expone dos receivers de webhook. No son para consumidores externos — reciben eventos del backend y del scraper monitor:

Método	Path	Auth	Descripción
POST	/api/webhooks/backend	HMAC vía WEBHOOK_SIGNING_SECRET	Eventos del backend (runs de pipelines, artifacts, sessions).
POST	/api/webhooks/scraper-monitor	HMAC vía PICKO_SCRAPER_SIGNING_SECRET	Eventos de diff del scraper monitor. Devuelve 503 cuando el scraper no está configurado.

Si querés consumir eventos del backend desde un servicio externo, el camino recomendado es el SSE stream de abajo.

Streaming

Método	Path	Descripción
GET	/api/stream	Feed Server-Sent Events de eventos del backend scopeado a la org activa. text/event-stream; heartbeat cada 15s. Query: ?events=<comma-separated> filtra por tipos de evento.

Auth: el mismo Bearer agent token. Reconectá con backoff en EventSource.onerror.

Lo que no está expuesto (común que se busque)

• No hay una superficie REST pública firmada con HMAC (/api/v1/whet/* no es un path real).
• No hay keys pk_live_* / pk_test_*. El agent token es la única credencial pública.
• No hay rutas admin POST /webhook_endpoints / POST /api_keys. Las suscripciones de webhooks y las API keys no se gestionan vía el API público hoy.
• Refinement se alcanza vía MCP (prompt refine_post) o, internamente, vía el route del backend. No hay endpoint público /refinements.

Para items del roadmap (auth multi-key, suscripciones públicas de webhooks, admin con scope), abrí un issue.