https://{instanceId}.agent37.app, with the same Authorization: Bearer sk_live_... header. The platform edge authenticates the key and checks the instance belongs to your workspace, then the gateway answers. See Instance URLs.
| Action | Endpoint |
|---|---|
| List sessions | GET /v1/sessions |
| Retrieve, with history | GET /v1/sessions/{id} |
| Delete | DELETE /v1/sessions/{id} |
| List models | GET /v1/models |
| Health and version | GET /v1/health · GET /v1/version |
You never create a session directly. The first
POST /v1/responses without a session_id mints one and returns its id; reuse that id to continue the thread.The session object
The session id: 32 hex characters, no prefix. Every response in the conversation carries it as
session_id.The agent the session runs.
hermes today.The session’s current model. Sending
model on a turn updates it; null until a turn sets one.The current model’s provider, e.g.
anthropic.When the session started, in epoch milliseconds.
When the last turn finished, in epoch milliseconds. Failed turns do not update it;
null until the first turn completes.Gateway timestamps are epoch milliseconds. The hosting API at
api.agent37.com uses epoch seconds.List sessions
GET /v1/sessions returns every session on the instance, newest first, wrapped in { "data": [...] }. The list carries session metadata only, never history, so it stays cheap to poll for a sidebar.
Retrieve a session with history
GET /v1/sessions/{id} returns the session object plus history: the full transcript, in order. You read it for display or audit; you never resend it, because the session already holds it. A session with no completed turns returns history: []. An unknown id returns 404 session_not_found.
Each entry in history is a message:
The message id. Treat it as opaque; it uses a different format from session and response ids.
The session the message belongs to.
user, assistant, or system.The message text.
The assistant’s reasoning for that turn, when the agent recorded any. Absent otherwise.
When the message was created, in epoch milliseconds.
Delete a session
DELETE /v1/sessions/{id} removes the conversation and returns exactly { "id": "...", "deleted": true }. The delete acts once: repeating it returns 404 session_not_found.
One turn at a time
A session runs one response at a time. Posting new input while a turn is in flight returns409 session_busy. Cancel the running turn with POST /v1/responses/{id}/cancel, or start the new input on another session. Two sessions on the same instance run independently.
List models
GET /v1/models lists the models the instance’s agent can run. The result is cached for about 60 seconds, so a newly available model can take up to a minute to appear.
The model used when a turn does not name one.
The provider of the default model.
One entry per model:
{ "id", "label", "provider", "is_default" }. Pass an entry’s id as model (with its provider) on a turn.model and provider are dials you set per turn on POST /v1/responses: omit them to keep the session’s current model, or send them to switch. A continuation that sets them updates the session’s stored model and provider for the turns that follow.
Health and version
GET /v1/health returns { "ok": true, "hermes": true }. ok is true whenever the gateway is up; hermes reports whether the agent worker behind it is reachable. Use it as a readiness probe after create or start.
GET /v1/version returns the gateway build, e.g. { "name": "agent37-gateway", "version": "0.1.0" }.
Next steps
Send a message
Start and continue sessions with
POST /v1/responses, the turn that fills these threads.Streaming
The full SSE event list for
stream: true, plus reconnect and cancel.Build a chat app
Put list, send, and continue together: one instance per user, one session per thread.
Instance URLs
How
{instanceId}.agent37.app routing and authentication work.