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 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) and responds JSON with Cache-Control: no-store.

Map

A complete turn

const base = "https://www.ghosty.studio/api/v2/me";const h = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
// 1. open a conversationconst { 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 headerses.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 completionawait 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 }] }),});

Attach something already in the account

Download everything: GET /api/v2/me/files?all=1 lists ALL the account's files (documents, conversations and what arrived through your agents' channels), 500 per page with nextCursor; each one has a group (documents | conversations | library). Each file downloads with GET /api/v2/me/files/:id (signed link). ghosty me files export uses it. A database downloads with GET /api/v2/agents/:id/dbs/:db/export (?format=sqlite, the default, or ?format=csv&table=T); only with the person's session, not with gat_.

GET /api/v2/me/files?q=contract (with q, even empty) returns your files: what you uploaded and what's in your personal conversations, never customer or test attachments. Each one has an id, a 15-min url for the thumbnail, and the next page in nextCursor. To send it to the agent you don't upload again: it goes by id.

await fetch(`${base}/agents/${agentId}/conversations/${sessionId}/messages`, {  method: "POST", headers: h,  body: JSON.stringify({ content: "Put this photo in the report", images: [{ fileId: "cmx…" }] }),});

The agent sees it as archivo:<id> and, in a later turn, fetches it again with its file_get tool (a fresh 15-min link). An id that isn't yours returns 404.

The browser's EventSource doesn't send headers; in Node use eventsource or fetch and read the body. Details of each event in Events.