# Referencia de la API

> Todos los endpoints de /api/v2/me — agentes, conversaciones, mensajes, eventos, permisos, archivos, conectores — con su esquema OpenAPI 3.1.

URL: https://www.ghosty.studio/docs/api/referencia

**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.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](/docs/api/autenticacion)) y responden JSON con `Cache-Control: no-store`.

## Mapa

| Recurso | Rutas |
|---|---|
| **Configuración del agente** (token `gat_`) | `GET/PATCH /api/v2/agents/:id`, `PUT/DELETE/GET …/files/*`, `GET …/skills`, `PUT/DELETE …/skills/:slug`, `GET/PUT …/mcp`, `POST …/restart` — ver [Configura tu agente](/docs/configurar) |
| Cuenta | `DELETE /api/v2/me` |
| Agentes | `GET /api/v2/me/agents` |
| Conversaciones | `GET/POST …/agents/:agentId/conversations`, `GET/PATCH/DELETE …/conversations/:sessionId` |
| Turnos | `POST …/:sessionId/messages` (202), `GET …/:sessionId/events` (SSE), `POST …/:sessionId/cancel` |
| Permisos y modelo | `POST …/:sessionId/permission`, `POST …/:sessionId/model` |
| Programados | `GET/POST …/:sessionId/schedule`, `DELETE …/:sessionId/schedule/:id` |
| Compartir | `GET/POST/DELETE …/:sessionId/share` |
| Archivos | `GET/POST /api/v2/me/files`, `GET/DELETE /api/v2/me/files/:id`, `POST /api/v2/me/stt` |
| Conectores | `GET /api/v2/me/connectors`, `POST …/:id/start`, `DELETE …/:id` |
| Dispositivos | `POST/DELETE /api/v2/me/devices` |

## 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ón
const { 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 headers
es.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 terminar
await 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 }] }),
});
```

`EventSource` del navegador no manda headers; en Node usa `eventsource` o `fetch` con lectura del body. Detalle de cada evento en [Eventos](/docs/api/eventos).