HTTP API

Start sessions, follow them over server-sent events, steer a run, and answer approvals and questions.

egin serve <dir> --port 8787 serves one agent. To put it behind a web app, see Frontends.

Authentication

Set EGIN_TOKEN and every route except /health and the channel routes needs Authorization: Bearer <token>. Requests without it get 401. The channel routes keep their own signature checks.

EGIN_TOKEN=... egin serve my-agent --host 0.0.0.0

Users

When many people share one agent, have your app’s server send X-Egin-User: <user id> on every request, after its own sign-in check. A session created with that header belongs to that user. With it, every session route reaches only that user’s sessions, and someone else’s answers 404, the same as one that doesn’t exist. GET /sessions lists only theirs. Requests without the header are the operator’s and reach every session.

The browser must never set the header itself: your server sets it, and EGIN_TOKEN keeps anyone else from calling egin directly.

By default egin serve listens on 127.0.0.1 only. It refuses any other --host unless EGIN_TOKEN is set, because anyone who can reach the port could run the agent and approve its tool calls.

Routes

Route Body Result
GET /sessions?limit=50 {"sessions": [{"id", "status", "created", "title"}]}, newest first, titled by the first message
GET /agent {"model", "models", "reasoning_effort", "reasoning_efforts"}: what a client may pick; reasoning_efforts maps each model to the efforts it takes
POST /sessions {"message"?, "model"?, "reasoning_effort"?, "output_schema"?}, or no body {"id"}; starts a run when a message is given
POST /sessions/{id}/messages {"message", "files"?, "model"?, "reasoning_effort"?} Continue a session; files are uploads from the route below. Sent while it runs, the message joins that run and the result is {"ok": true, "queued": true} (see Messages during a run)
POST /sessions/{id}/files?name=<name> The raw file {"name", "path", "size"}; saved under uploads/<session>/ in the workspace, up to 25 MB
GET /sessions/{id} Status, stats and messages
GET /sessions/{id}/events?after=<id> Server-sent events
GET /sessions/{id}/history?before=<id>&limit=500 {"events", "earlier"}: a page of the stored log, oldest first, starting at a turn; earlier is the before for the page ahead, or null
POST /sessions/{id}/approvals {"call_id", "allow"} Answer an approval request
POST /sessions/{id}/answers {"call_id", "answer"} Answer a question from ask_user
POST /mcp JSON-RPC The agent as an MCP server, with channels/mcp.toml; see Channels
POST /sessions/{id}/cancel Stop a running session
DELETE /sessions/{id} Stop it, remove its VM, delete its records
GET /health ok, with no token needed, for a host’s health check

A model must be the agent’s own or one listed in its models, and reasoning_effort one the model takes: low to max for Claude, none to max for OpenAI’s GPT models (both when called directly, not through the AI Gateway), and low, medium or high for the rest. Anything else is a 400. Either one stays with the session for later turns until a message changes it; switching to a model that does not take the session’s effort drops the effort.

Start a session

curl -X POST localhost:8787/sessions \
  -H 'content-type: application/json' \
  -d '{"message": "Check the HTTP health of every target."}'

Follow it

curl -N localhost:8787/sessions/<id>/events

The stream replays the stored log first, then sends live events as they happen. Reconnect with ?after=<last event id> to pick up exactly where you left off.

Event Meaning
user A message the session received, as the model sees it
queued A message sent during a run, waiting for the run to take it up; its user event follows when it does
question ask_user put a question (question, options) and waits for an answer
answer The answer to a question
hook hooks/done sent the run on with a new message
data Structured data a tool sent for the UI (::data lines), with its call_id
unlocked A tool or skill made locked tools available (by, tools)
output A final_answer that fit the session’s output_schema
token A piece of the reply as it streams. Not stored, so it has no id and is not replayed
reasoning A piece of the model’s reasoning, where the model shows it. Not stored
assistant A complete model reply, with its tool calls
tool_call The agent called a tool
approval_request A tool call is waiting for an answer
approval The answer to an approval request
tool_started A tool call began running
tool_result The tool’s result
file_seen The agent looked at an image or document
subagent A subagent started; session is its own session. Its answer comes back as the task call’s tool_result
web_search, web_extract The You.com router searched or read a page on the model’s behalf (web = "server")
elided Old tool output was stubbed out to make room
summarised Old turns were summarised to make room
wrap_up A turn or spend limit was reached; one last answer follows
done The run finished
error The run failed
cancelled The run was stopped

A run ends with exactly one of done, error or cancelled, so a client that follows a turn should stop on any of the three.

Every event carries at, when it happened in Unix milliseconds. An assistant event also carries model, cost in dollars, and ms, how long the model call took.

Structured output

Give a session output_schema, a JSON Schema, and its runs end with a value that fits it instead of free text:

curl -X POST localhost:8787/sessions -H 'content-type: application/json' -d '{
  "message": "Triage this alert: disk at 97% on db-1",
  "output_schema": {"type": "object", "required": ["severity", "summary"],
    "properties": {"severity": {"enum": ["low", "high"]}, "summary": {"type": "string"}}}}'

The model gets a final_answer tool whose parameters are the schema. Its value is checked (types, required fields, enums, nested objects and arrays); one that doesn’t fit goes back to the model with what is wrong. An answer in plain text is sent back twice at most. The run’s done event then carries the value as output, and its text is the same value as JSON. The schema stays with the session for later turns; a message with "output_schema": null clears it. From the command line: egin run my-agent "..." --schema schema.json prints the JSON.

Messages during a run

A message sent while the session runs is not refused. It is stored, emits queued, and joins the run as mid_run in agent.toml says:

  • steer (the default): the model sees it at its next step, after the tool calls in flight have their results. Use it to correct course: “also check the logs”, “skip the tests”.
  • queue: the model finishes its current answer first, then takes the message as the next turn, in the same run.

Either way the run ends with one done. A message is stored before it is acknowledged, so a restart doesn’t lose it. A change of model or reasoning_effort is refused (409) while the session runs.

Approvals

With approval = "ask", a call to an unsafe tool emits approval_request with a call_id and waits. With approval = "once", only the first call to each tool in a session asks; a yes holds for that tool’s later calls. The request carries policy so a UI can say which. Answer it:

curl -X POST localhost:8787/sessions/<id>/approvals \
  -H 'content-type: application/json' \
  -d '{"call_id": "<call id>", "allow": true}'

The answer is stored, so it survives a restart. An answer that arrives after a restart but before the server has picked the session up again is stored too, and the run uses it when it gets there.

A subagent asks on its own session: its approval_request arrives on the stream of the session named in the parent’s subagent event, and is answered at POST /sessions/<subagent session>/approvals. The subagent’s session belongs to the parent’s user. The egin client does this for you; see Frontends.

Questions

With ask = true in agent.toml, the agent has an ask_user tool for a decision or a fact only the user has. It emits question with a call_id, the question and any options, and waits:

curl -X POST localhost:8787/sessions/<id>/answers \
  -H 'content-type: application/json' \
  -d '{"call_id": "<call id>", "answer": "staging"}'

The answer can be one of the options or free text. Like approvals, it is stored and survives a restart. With egin run, the question is asked in the terminal. Where no one can answer (egin run --yes, evals), the tool tells the model to decide for itself and say what it assumed.