Developers

The Agent API

Send Sochen a task from a script, a server or another AI agent, and get the answer back. Each run is an ordinary Sochen chat on your account, so it has your memory, tools and pets’ skills, and anything that needs your OK still waits for you in the app. Comes with Pro.

Overview

One endpoint: POST /api/v1/run with a message. Sochen starts a chat, works the task the way it would in the app (searching, reading pages, using your connected apps and your pets’ skills) and answers when the turn is done, waiting up to four minutes. Every run appears in your chat list, so you can follow or pick it up in the app.

Your key

Make a key in Settings → API keys. It’s shown once; keep it on your server and send it as Authorization: Bearer sk_sochen_…. Revoke it in Settings at any time.

Run a task

Request
curl https://sochen.dev/api/v1/run \
  -H "Authorization: Bearer $SOCHEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Find three Google reviews of Blue Bottle Coffee in Oakland and sum them up in two lines."}'
Response
{
  "status": "answered",
  "answer": "(Sochen's two-line summary of the reviews)",
  "chat_id": "ses_…",
  "chat_url": "https://sochen.dev/s/ses_…"
}

Continue a chat

Send the chat_id you got back to keep the same conversation and its context.

Request
curl https://sochen.dev/api/v1/run \
  -H "Authorization: Bearer $SOCHEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "ses_…", "message": "Now the same for Sightglass in San Francisco."}'

What comes back

  • answered with the answer.
  • needs_approval when the task reached a step that needs your OK (below).
  • working (HTTP 202) when it ran past four minutes: send another message to the chat_id later, or follow it in the app.
  • failed with what went wrong.

Approvals

Anything that sends, buys, books or changes something asks you first, in the app, the same as in a chat. The API can’t approve it: the response says what’s waiting and links the chat.

Response
{
  "status": "needs_approval",
  "answer": "(what Sochen did before it stopped to ask)",
  "note": "Sochen needs the person's OK before it can run send email; approve it in the app.",
  "chat_id": "ses_…",
  "chat_url": "https://sochen.dev/s/ses_…"
}

Limits and billing

Runs use your plan’s credits like any chat (Billing lists every turn). Up to 60 runs an hour per account; a turn waits up to four minutes for its answer.

Errors

Errors come back as { "error": "…" } with one of these statuses:

400
The body isn't JSON with a message (and an optional chat_id).
401
No key, or a key that's revoked or isn't a Sochen key.
402
Not enough credits for the turn.
403
The account isn't on Pro.
404
The chat_id isn't one of this account's chats.
423
The account is frozen.
429
More than 60 runs in an hour.
502
The turn failed; the answer says why, and the chat has the details.