Documentación
API

Referencia de la API

Todos los endpoints de /api/v2 — configuración del agente, bases de datos, documentos, turnos, WhatsApp, tableros, cuenta, conversaciones, archivos y partners — con su esquema OpenAPI 3.1.

Actualizado 2026-10-01

Abrir en Claude ↗Abrir en ChatGPT ↗?

Pruébala desde aquí: en el visor de abajo, pega el token de tu agente (Agentes → tu agente → Generar token) en el campo de autenticación agentToken y ejecuta GET /api/v2/agents/{id}; las llamadas salen contra la API real.

La especificación completa está en (OpenAPI 3.1). Abajo se renderiza; puedes importarla en Postman, Bruno o generar un cliente con openapi-generator.

Base: https://www.ghosty.studio. Todas las rutas exigen Authorization: Bearer () y responden JSON con Cache-Control: no-store.

Mapa

RecursoRutas
Configuración del agente (token gat_ o sesión)GET/PATCH/DELETE /api/v2/agents/:id, PUT/DELETE/GET …/files/*, GET …/skills, GET/PUT …/skills/house, PUT/PATCH/DELETE …/skills/:slug, GET/PUT …/mcp, POST …/restart, GET …/templates, GET/POST/DELETE …/shares, GET/POST/DELETE …/teams, GET/PUT …/demo — ver y
El agente como archivoGET …/export (YAML) y POST …/apply (plan y aplicar), con tu sesión (no gat_); GET/POST …/bundle (estilo Eve) ·
Bases de datos y fotosGET …/dbs, PUT/DELETE …/dbs/:db, POST …/dbs/:db/query, GET …/dbs/:db/export, POST …/dbs/:db/import, POST …/dbs/:db/rehost, POST …/dbs/:db/photos · ,
DocumentosGET/POST …/documents, PUT/DELETE …/documents/:doc, GET/POST …/documents/:doc/versions, POST …/versions/:n/restore ·
Turnos y diagnósticoPOST …/try, GET …/turns, GET …/turns/:turnId, GET …/doctor, GET/POST …/box · ,
WhatsAppGET/PUT …/whatsapp, POST …/whatsapp/link, POST …/whatsapp/history, GET/POST/DELETE …/wa, GET/POST …/wa/groups, POST …/wa/import, GET …/channels/links (quién contestó por última vez; orphans=1) · , ,
Tableros y tarjetasPOST …/board/archive, GET …/board/conversations, GET …/board/conversations/:ref, POST …/board/conversations/:ref/pause, POST …/board/conversations/:ref/reply, GET …/board/pending, GET/POST/DELETE /api/v2/workspaces/:slug/boards, POST …/boards/move-cards ·
CuentaGET/DELETE /api/v2/me, GET /api/v2/me/usage, GET /api/v2/me/credentials, PUT/DELETE …/credentials/:provider · ,
Bitácora y fábricaGET /api/v2/audit · GET /api/v2/workspaces/:slug/factory/runs, GET/POST …/factory/runs/:runId · GET /api/v2/teams/handles · ,
AgentesGET /api/v2/me/agents · POST /api/v2/me/agents (crear, scope agents:write; dryRun, workspace, like…) · GET …/agents/:agentId/schedule, GET …/agents/:agentId/tasks ·
ConversacionesGET/POST …/agents/:agentId/conversations, GET/PATCH/DELETE …/conversations/:sessionId (?archivos=1 trae también sus archivos), GET /api/v2/me/conversations?agentes=a,b (las listas de varios agentes en una respuesta)
TurnosPOST …/:sessionId/messages (202), GET …/:sessionId/events (SSE), POST …/:sessionId/cancel
Permisos y modeloPOST …/:sessionId/permission, POST …/:sessionId/model
ProgramadosGET/POST …/:sessionId/schedule, DELETE …/:sessionId/schedule/:id
CompartirGET/POST/DELETE …/:sessionId/share
ArchivosGET/POST /api/v2/me/files, GET/DELETE /api/v2/me/files/:id, POST /api/v2/me/stt
ConectoresGET /api/v2/me/connectors, POST …/:id/start, POST …/:id/credentials, DELETE …/:id
MemoriasGET/POST /api/v2/me/memories, PATCH/DELETE /api/v2/me/memories/:id
Hilo largoPOST /api/v2/me/agents/:agentId/conversations/:sessionId/continue
DispositivosPOST/DELETE /api/v2/me/devices
Partners (credencial gpk_/gps_)/api/v2/partner, …/partner/credentials[/:id[/rotate]], …/partner/audit, GET …/partner/usage, …/partner/agent, …/partner/tenants[/:externalId], POST …/partner/turns ·

Un turno completo

typescript
const base = "https://www.ghosty.studio/api/v2/me";const h = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
// 1. abre una conversaciónconst { id: sessionId } = await (await fetch(`${base}/agents/${agentId}/conversations`, { method: "POST", headers: h })).json();
// 2. suscríbete a los eventos ANTES de mandar (el stream reproduce lo ya emitido, así que el orden no es crítico)const es = new EventSource(`${base}/agents/${agentId}/conversations/${sessionId}/events`); // añade el bearer con un polyfill que acepte headerses.addEventListener("chunk", (e) => process.stdout.write(JSON.parse(e.data).text));es.addEventListener("done", () => es.close());
// 3. manda el mensaje: responde 202 al aceptarlo, no al terminarawait fetch(`${base}/agents/${agentId}/conversations/${sessionId}/messages`, {  method: "POST", headers: h,  body: JSON.stringify({ content: "Resume este PDF en 5 líneas", images: [{ name: "contrato.pdf", mimeType: "application/pdf", data: base64 }] }),});

Adjuntar algo que ya está en la cuenta

Descargar todo: GET /api/v2/me/files?all=1 lista TODOS los archivos de la cuenta (documentos, conversaciones y lo que llegó por los canales de tus agentes), 500 por página con nextCursor; cada uno trae group (documents | conversations | library). Cada archivo se baja con GET /api/v2/me/files/:id (liga firmada). Lo usa ghosty me files export. Una base se descarga con GET /api/v2/agents/:id/dbs/:db/export (?format=sqlite, default, o ?format=csv&table=T); sólo con la sesión de la persona, no con gat_.

GET /api/v2/me/files?q=contrato (con q, aunque vaya vacío) devuelve tus archivos: lo que subiste y lo de tus conversaciones personales, nunca adjuntos de clientes ni de pruebas. Cada uno trae id, una url de 15 min para la miniatura y la página siguiente en nextCursor. Para mandarlo al agente no se vuelve a subir: va por id.

typescript
await fetch(`${base}/agents/${agentId}/conversations/${sessionId}/messages`, {  method: "POST", headers: h,  body: JSON.stringify({ content: "Mete esta foto en el reporte", images: [{ fileId: "cmx…" }] }),});

El agente lo ve como archivo:<id> y, en un turno posterior, lo vuelve a traer con su tool file_get (liga nueva de 15 min). Un id que no es tuyo responde 404.

EventSource del navegador no manda headers; en Node usa eventsource o fetch con lectura del body. Detalle de cada evento en .

← Anterior
Autenticación
Siguiente →
Eventos (SSE)