# API reference

> Every endpoint of /api/v2/me — agents, conversations, messages, events, permissions, files, connectors — with its OpenAPI 3.1 schema.

URL: https://www.ghosty.studio/en/docs/api/reference

**Try it from here**: in the viewer below, paste your agent's token (Agents → your agent → Generar token) into the `agentToken` auth field and run `GET /api/v2/agents/{id}`; calls go against the real API.

The full specification is at [`/openapi.yaml`](/openapi.yaml) (OpenAPI 3.1). It is rendered below; you can import it into Postman or Bruno, or generate a client with `openapi-generator`.

Base: `https://www.ghosty.studio`. Every route requires `Authorization: Bearer` ([Authentication](/en/docs/api/authentication)) and responds JSON with `Cache-Control: no-store`.

## Map

| Resource | Routes |
|---|---|
| **Agent configuration** (`gat_` token) | `GET/PATCH /api/v2/agents/:id`, `PUT/DELETE/GET …/files/*`, `GET …/skills`, `PUT/DELETE …/skills/:slug`, `GET/PUT …/mcp`, `POST …/restart` — see [Configure your agent](/en/docs/configure) |
| Account | `DELETE /api/v2/me` |
| Agents | `GET /api/v2/me/agents` |
| Conversations | `GET/POST …/agents/:agentId/conversations`, `GET/PATCH/DELETE …/conversations/:sessionId` |
| Turns | `POST …/:sessionId/messages` (202), `GET …/:sessionId/events` (SSE), `POST …/:sessionId/cancel` |
| Permissions and model | `POST …/:sessionId/permission`, `POST …/:sessionId/model` |
| Scheduled | `GET/POST …/:sessionId/schedule`, `DELETE …/:sessionId/schedule/:id` |
| Sharing | `GET/POST/DELETE …/:sessionId/share` |
| Files | `GET/POST /api/v2/me/files`, `GET/DELETE /api/v2/me/files/:id`, `POST /api/v2/me/stt` |
| Connectors | `GET /api/v2/me/connectors`, `POST …/:id/start`, `DELETE …/:id` |
| Devices | `POST/DELETE /api/v2/me/devices` |

## A complete turn

```typescript
const base = "https://www.ghosty.studio/api/v2/me";
const h = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };

// 1. open a conversation
const { id: sessionId } = await (await fetch(`${base}/agents/${agentId}/conversations`, { method: "POST", headers: h })).json();

// 2. subscribe to events BEFORE sending (the stream replays what was already emitted, so the order isn't critical)
const es = new EventSource(`${base}/agents/${agentId}/conversations/${sessionId}/events`); // add the bearer with a polyfill that accepts headers
es.addEventListener("chunk", (e) => process.stdout.write(JSON.parse(e.data).text));
es.addEventListener("done", () => es.close());

// 3. send the message: responds 202 on acceptance, not on completion
await fetch(`${base}/agents/${agentId}/conversations/${sessionId}/messages`, {
  method: "POST", headers: h,
  body: JSON.stringify({ content: "Summarize this PDF in 5 lines", images: [{ name: "contract.pdf", mimeType: "application/pdf", data: base64 }] }),
});
```

The browser's `EventSource` doesn't send headers; in Node use `eventsource` or `fetch` and read the body. Details of each event in [Events](/en/docs/api/events).