Referencia de la API

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.yaml (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 (Autenticación) y responden JSON con Cache-Control: no-store.

Mapa

Un turno completo

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.

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 Eventos.

Avisos a tu app desde fuera (crons)

Un token personal de push (gpu_…) deja que algo de fuera —un cron de EasyBits, un script— te mande un aviso al teléfono. Sólo sirve para eso y sólo te llega a ti.

# 1. Sácalo con tu sesión o bearer (el valor sale una sola vez)curl -X POST https://www.ghosty.studio/api/v2/me/push-tokens -H "Authorization: Bearer $GS_TOKEN" -d '{"name":"cron estudio"}'# 2. Úsalocurl -X POST https://www.ghosty.studio/api/v2/me/push -H "Authorization: Bearer gpu_…" \  -H "Content-Type: application/json" -d '{"title":"Hora de estudiar","body":"Media hora antes del café."}'

Body: title (obligatorio), body, url (https, la app la abre), agentId + sessionId (abre ese chat), urgent, tag. Responde {ok, devices}; devices: 0 = no tienes la app con sesión. Revocar: DELETE /api/v2/me/push-tokens?id=….