Session API

Create Studio sessions programmatically — no browser flow required. This is the entry point for one-shot automation: pass an initial prompt at creation and the AI agent starts building as soon as the session is ready, with no further input.

Base URL and authentication

Studio is not reachable directly. All requests go through the Hailer API, which acts as an authenticated proxy — Studio's endpoints are mounted under the /proxy/studio path prefix:

https://api.hailer.com

The proxy requires valid Hailer credentials on every request — pass a user API key in the Authorization header (the raw key, no Bearer prefix). Unauthenticated requests are rejected with 401 before they reach Studio.

Two error shapes exist, depending on which layer rejects the request: the proxy itself answers { "error": "…" } (e.g. 401 { "error": "Unauthorized" }), while Studio endpoints answer with the { "ok": false, "error": "…" } envelope used throughout this page.

Treat your API key like a password

Anyone holding the key can act as its user. Keep it server-side only — never embed it in client-side code, mobile apps, or version control.

Create a session

POST /proxy/studio/api/sessions/create
Content-Type: application/json

Request body

Field	Type	Required	Description
apiKey	string	✅	Hailer user API key. The key's user must be an owner or admin of the target workspace.
workspaceId	string	✅	The Hailer workspace the session develops against.
initialPrompt	string	—	First message handed to the AI agent once the session is ready. This enables one-shot flows: describe the whole idea up front and the agent builds it unattended.
systemMessage	string	—	System-prompt override accompanying initialPrompt — shapes the agent's behavior (persona, constraints) for that first turn. Ignored without initialPrompt.

Response — 202 Accepted

{
  "ok": true,
  "sessionId": "6650f2…",
  "state": "initializing"
}

Session creation is asynchronous: the response returns immediately while the environment is prepared in the background (typically ready in under a minute). The session then transitions to active — or to error if setup failed.

Errors

Every error has the shape { "ok": false, "error": "…" }.

Status	Meaning
400	Missing apiKey/workspaceId, or initialPrompt/systemMessage is not a string
401	The API key failed validation against Hailer
403	The key's user is not an owner or admin of workspaceId
500	User info could not be resolved from Hailer — retry later

Example — one-shot session

curl -X POST "https://api.hailer.com/proxy/studio/api/sessions/create" \
  -H "Authorization: $HAILER_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "'"$HAILER_USER_API_KEY"'",
    "workspaceId": "664a1b…",
    "initialPrompt": "Build a CRM app with a sales pipeline workflow and a dashboard showing deals per phase.",
    "systemMessage": "Prefer simple, minimal implementations. Ask no questions."
  }'

Check session state

Lists all your sessions across workspaces — poll it after creating a session and wait for its state to become active.

GET /proxy/studio/api/bootstrap

No body and no query parameters — the user is resolved from the credentials on the request.

Response — 200 OK

{
  "ok": true,
  "serverVersion": "1.2.2",
  "hasValidCredentials": true,
  "sessions": [
    {
      "id": "6650f2…",
      "name": "brave-blue-falcon",
      "workspaceId": "664a1b…",
      "state": "active",
      "archivedAt": null,
      "lastActivityAt": "2026-07-28T09:14:03.512Z",
      "createdAt": "2026-07-28T09:02:41.007Z",
      "updatedAt": "2026-07-28T09:14:03.512Z"
    }
  ]
}

Field	Type	Description
serverVersion	string	Version of the Studio server answering the request
hasValidCredentials	boolean	Whether Studio holds a valid stored Hailer API key for the user — false means the next session create/resume will require credentials again
sessions	array	All of the user's sessions, most recently updated first
sessions[].id	string	Session id — match it against the sessionId returned by create
sessions[].name	string	Display name, editable in the Studio UI
sessions[].workspaceId	string	The Hailer workspace the session belongs to
sessions[].state	string	Lifecycle state: initializing, active, idle, suspended, or error
sessions[].archivedAt	string | null	When the session's project files were last snapshotted to storage, null if never
sessions[].lastActivityAt	string | null	Timestamp of the last activity in the session
sessions[].createdAt	string	When the session was created
sessions[].updatedAt	string	Last change to the session record — this drives the list order

Errors

Status	Meaning
401	Missing or invalid credentials

Example — poll until active

curl "https://api.hailer.com/proxy/studio/api/bootstrap" \
  -H "Authorization: $HAILER_USER_API_KEY"