Sai HTTP API

Verify the caller’s credentials and return their identity. Useful as a health check before storing a credential.

{ "ok": true, "userId": "abc123", "authType": "apiKey" }

List all machines registered to the user, sorted by name.

{
  "machines": [
    {
      "machineId": "m_1a2b",
      "name": "MacBook Pro",
      "updatedAt": 1750000000000,
      "status": "hibernated",
      "canWake": true
    }
  ]
}

status is one of active, hibernated, hibernating or wakingup, and is omitted for a machine that has never reported one — read that as offline. canWake says whether a hibernated machine can be brought back remotely at all; it follows from where the machine is hosted, not from what it is doing now.

Read both before telling a user anything. A machine that is hibernated with canWake: false is asleep and staying that way, so “it’ll be up in a minute” is a promise nothing can keep — status alone cannot tell you that. POST /v1/agents/wake is how you act on it.

Resolve the user’s most-recently-active machine and the CLI session on it. Returns 404 if no machine is registered.

{ "machineId": "m_1a2b", "sessionId": "s_9z8y" }

sessionId is omitted until the CLI has a session on that machine, so a fresh machine returns { "machineId": "m_1a2b" } alone. This endpoint never creates one, and unlike /context and /sessions it takes no channel — it always reports the CLI’s. For your own, read the data-session event at the head of your stream.

List your 20 most-recent sessions on a machine, newest first — desktop conversations included, other accounts’ never. Requires a machineId query parameter. active: true marks the current session of the channel you name — not whatever the desktop is currently showing. Pass channel=api or the flag points at the CLI’s.

curl "https://api.sai.simular.ai/v1/agents/sessions?machineId=m_1a2b&channel=api" \
  -H "Authorization: Bearer sapi_..."

{
  "sessions": [
    { "sessionId": "s_9z8y", "title": "Email action items", "updatedAt": 1750000000000, "active": true }
  ]
}

The listing is read-only, and the ids in it aren’t an address: no endpoint takes a session id, so nothing here repoints the API at an older conversation. POST /v1/agents/new-session is the only thing that moves it. To reach an older conversation, ask the agent about it.

Rotate the named channel’s conversation on a machine: a fresh session is created and becomes the one that channel reads and writes. The previous session is not deleted — it becomes an ordinary past one, so it stays readable in the desktop app and searchable by the agent, transcript and title intact. The desktop app’s own conversation is untouched.

Body

{ "machineId": "m_1a2b", "channel": "api" }

{ "sessionId": "s_new123" }

Fetch recent messages from the named channel’s conversation — with channel=api, what you sent and what came back, and never what the desktop user has been doing. Query params: machineId (required), channel (cli or api, defaults to cli), and limit (default 30, max 100 — a missing, non-numeric, or non-positive value falls back to the default).

curl "https://api.sai.simular.ai/v1/agents/context?machineId=m_1a2b&channel=api&limit=10" \
  -H "Authorization: Bearer $SAI_API_KEY"

{
  "messages": [
    { "role": "user", "content": "list my unread emails", "timestamp": 1750000000000 },
    { "role": "assistant", "content": "You have 3 unread emails...", "timestamp": 1750000005000 }
  ]
}

Returns { "messages": [] } when that channel has no session yet on the machine. A GET never creates one. This is the endpoint a conversational client answers “what were we just doing” from, so getting channel right is the difference between its own history and a terminal transcript it never wrote to.

Upload a file to attach to a message. Send the raw file bytes as the request body and the filename in an x-filename header (URL-encoded). The MIME type is derived server-side from the extension. Call this before POST /v1/agents/message and pass the returned object in attachments.

curl -X POST https://api.sai.simular.ai/v1/agents/upload \
  -H "Authorization: Bearer sapi_..." \
  -H "x-filename: workflow.sim" \
  --data-binary @./workflow.sim

{
  "path": "uploads/workflow-1750000000000.sim",
  "name": "workflow.sim",
  "mime": "text/plain",
  "size": 1024,
  "downloadUrl": "https://firebasestorage.googleapis.com/v0/b/.../o/...?alt=media&token=..."
}

Send a message to the agent. The response is a Server-Sent Events stream (the Vercel AI SDK v6 UI Message Stream protocol) that emits the agent’s narrations, tool activity, approval requests, and final text until the task completes.

The message lands in this machine’s API session, creating it on the first call. There is no session parameter — each message continues the previous one.

Body

{
  "machineId": "m_1a2b",
  "message": "list my unread emails from today",
  "attachments": [
    {
      "path": "uploads/workflow-1750000000000.sim",
      "name": "workflow.sim",
      "mime": "text/plain",
      "size": 1024,
      "downloadUrl": "https://firebasestorage.googleapis.com/..."
    }
  ]
}

attachments is optional and accepts the objects returned by /v1/agents/upload.

Request

curl -N -X POST https://api.sai.simular.ai/v1/agents/message \
  -H "Authorization: Bearer sapi_..." \
  -H "Content-Type: application/json" \
  -d '{"machineId":"m_1a2b","message":"list my unread emails"}'

Response (SSE)

data: {"type":"start"}
data: {"type":"data-status","data":{"text":"Sai is working on this..."}}
data: {"type":"reasoning-start","id":"r1"}
data: {"type":"reasoning-delta","id":"r1","delta":"Opening Gmail..."}
data: {"type":"reasoning-end","id":"r1"}
data: {"type":"text-start","id":"t1"}
data: {"type":"text-delta","id":"t1","delta":"You have 3 unread emails: ..."}
data: {"type":"text-end","id":"t1"}
data: {"type":"finish","finishReason":"stop"}
data: [DONE]

See streaming events for the full event catalogue, and consuming the stream for a typed schema and readUIMessageStream / useChat integration.

Every message reaches the agent

This endpoint is pure delivery: no phrase is intercepted and handled server-side. Words that read like instructions to the platform — restart agent, always approve, or a bare yes while an approval is pending — are written to the transcript and forwarded to the agent like any other text. Use the dedicated endpoints for those: POST /v1/agents/approve names a specific approvalId rather than relying on what happens to be pending, and POST /v1/agents/restart restarts the agent.

The stream opens with a data-session event carrying the resolved sessionId. That is the only place you learn which session the turn landed in, since GET /v1/agents/session reports the CLI’s.

Errors

Failures before the stream opens are plain JSON with a status code — 403 for a machine that isn’t yours, 400 for an attachment URL that isn’t one of your uploads, 429 over the hourly limit. Once headers have flushed, every failure arrives as a terminal error event instead, so a fault while the message is being routed ends the stream rather than hanging it.

Resolve a pending approval surfaced by a data-approval-request event during a message stream. The original stream stays open and the agent continues once resolved.

Body

{ "approvalId": "ap_123", "response": "yes" }

response is one of yes, no, or always. Requests with isLinkOnly can’t be resolved here at all; they need the desktop app.

always is re-derived server-side rather than taken on trust, so sending it where the event didn’t set allowAlways doesn’t fail — it quietly resolves as a one-time approved instead. Check the returned status if the distinction matters: a dangerous shell command never becomes a standing approval.

{ "ok": true, "status": "approved" }
// status is "approved", "approved_always", or "denied"

Answering a choice

An approval with approvalType: "choice" is a question, not a permission — it needs the picks in selections, one inner array per question in the order the event listed them. Read the options from questions on the approval-request event and send option values, not labels:

{ "approvalId": "ap_123", "response": "yes", "selections": [["staging"]] }

Approving a choice without selections returns 422 and leaves it pending, so a bare yes is never enough to unblock the agent. Denying one resolves it with no picks — any selections you send alongside no are dropped.

Picks are validated against what was actually offered, since they’re handed to the agent as your answer. 422 comes back for a value that wasn’t among the options (unless the question set allowOther, or offered none at all, which makes it free text), for more than one pick on a question that isn’t multiple, for the wrong number of groups, and for selections on an approval that isn’t a choice. Payloads are bounded — at most 10 groups of 50 picks, each under 2000 characters — and exceeding that is a 400.

Abort the task running in the CLI session. It stops what sai started and leaves a task the desktop user launched running. Idempotent — safe to call when nothing is running.

Body

{ "machineId": "m_1a2b" }

{ "ok": true, "aborted": true }
// or, when the CLI session is idle or doesn't exist yet:
{ "ok": true, "aborted": false, "reason": "no active session" }

Aborting also denies any approvals still pending in that session — the task is going away, so nothing is left waiting on an answer that would never come. Approvals raised in other sessions on the machine are untouched. Cleanup is best-effort: it can’t fail the abort, so a successful response doesn’t guarantee every approval was resolved.

Restart the agent process or the full cloud machine. Returns 422 if restart is not supported for the workspace type.

Body

{ "machineId": "m_1a2b", "target": "agent" }

target is agent (just the Sai process) or machine (full VM, slower).

agent restarts the agent serving the CLI session, leaving the desktop user’s agent alone. When the CLI has no session on the machine it falls back to restarting the agent for the whole machine — which is the one case where this does reach your API work, by restarting everything.

{ "ok": true, "action": "restarted" }

Wake a hibernated machine without sending it any work. Use it when you need the machine up before you have anything to give it — binding a voice call to one, or switching a session onto one — so the spin-up runs while the user is still talking instead of inside their first real request.

Body

{ "machineId": "m_1a2b" }

{
  "ok": true,
  "waking": true,
  "startingUp": true,
  "status": "hibernated",
  "canWake": true
}

Branch on startingUp, not waking. waking is true only when this call was the one that dispatched, so it is false for a machine already on its way up — where a second dispatch would be wrong but the user is still owed the minute. startingUp covers both. status is read before the dispatch, which is what lets you tell one waking: false from another: active means there was nothing to do, hibernated with canWake: false means it is not coming back.

Safe to call redundantly, and 404 — not 403 — for a machine that isn’t yours. A wake takes roughly a minute and nothing here waits for it: poll GET /v1/agents/machines for status, or just send the work and let the stream report it.

The same send contract as POST /v1/agents/message — identical body, identical stream — on a second channel. The difference is whose conversation you join: this writes to the sai CLI’s session and gets the concierge side track below, while /v1/agents/message is the generic lane with its own session and no side track. The 60/hour message limit is counted per user across both, so switching channels buys no extra budget.

curl -N -X POST "https://api.sai.simular.ai/v1/cli/message" \
  -H "Authorization: Bearer $SAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "machineId": "m_1a2b", "message": "run the test suite" }'

Poll for conversational replies about your request — that the machine is waking up, for instance — as opposed to the agent’s own output, which arrives on the message stream. These are written after the message is delivered, so the send path never waits on them. Poll this while the stream is open and merge the two feeds.

Query params: machineId (required), since (exclusive, unix ms), limit (default 20, max 50), and seed=1 on the first poll of a message.

curl "https://api.sai.simular.ai/v1/cli/concierge-messages?machineId=m_1a2b&since=1750000000000&seed=1" \
  -H "Authorization: Bearer $SAI_API_KEY"

{
  "sessionId": "cs_9f8e",
  "serverNowMs": 1750000001234,
  "messages": [
    { "id": "cm_1", "role": "assistant", "content": "Waking your machine up...", "timestamp": 1750000000500 }
  ]
}

Use the returned serverNowMs as the since for your next poll. That keeps the cursor on the server’s clock, which is what these timestamps are written against — seeding since from your own clock is only reasonable on the first request, and only because seed=1 tells the server to tolerate the skew by clamping it to a two-minute window. Without that, a fast local clock silently filters out every reply and a slow one replays replies from an earlier call.

Before your first message the machine has no CLI session, so sessionId is null and messages is empty — a GET never creates one. An unknown machine is a 404; a missing machineId or a negative since is a 400. Replies are a side channel and not guaranteed: expect an empty list most of the time, and never block on one arriving.

Generate a long-lived API key. The plaintext key is returned once — only its hash is stored. Maximum 10 keys per account.

Body

{ "name": "ci-pipeline" }

{ "key": "sapi_AbC123...", "keyId": "k_456", "name": "ci-pipeline" }

List API keys for the authenticated user (IDs and labels only — never the plaintext secret).

{
  "keys": [
    { "keyId": "k_456", "name": "ci-pipeline", "createdAt": 1750000000000, "lastUsedAt": 1750000500000 }
  ]
}

Revoke an API key by ID. Returns 204 No Content on success.

curl -X DELETE https://api.sai.simular.ai/v1/account/keys/k_456 \
  -H "Authorization: Bearer <firebase-id-token>"