Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agent37.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

POST /v1/responses is the core call. It runs your input through an agent and returns the result. The call is agentic by default: the agent can browse, run code, use a terminal, read and write files, call connected tools, and reason across many steps before answering. Send an instance_id to start a conversation, or a session_id to continue one. The session keeps the full history, so you send only the new input.

​
Request body

​
input
string
required
The message or task. Reference uploaded files by path; see Continue a conversation for how history carries across turns.
​
instance_id
string
Which agent to talk to. With no session_id, this starts a new conversation and the reply returns its session_id. Required when you are not continuing a session.
​
session_id
string
Continue an existing conversation. The instance is implied, so you don’t send instance_id too.
​
agent
string
For a multi-agent template, which agent this new conversation uses (e.g. claude-code). Defaults to the template’s primary and is fixed once the session starts. Single-agent templates ignore it.
​
stream
boolean
true returns a Server-Sent Events stream; false (the default) returns the finished response as one JSON body. See Streaming events.
​
model
string
The LLM the agent runs on. List what the agent can run with GET /v1/models. Defaults to the session’s model.
​
provider
string
The model’s provider, e.g. anthropic.
​
reasoning_effort
string
How hard the model thinks: none, minimal, low, medium, high, or xhigh.
​
mode
string
chat (the default) runs one turn and replies. goal lets the agent work on its own, turn after turn, until the task is done or a safety cap is hit. Cancel it any time. Goal is supported by Hermes, Claude Code, and Codex.
​
metadata
object
Up to 16 key/value pairs. Echoed back on the response, never interpreted.

​
Response

​
id
string
The response id, prefixed resp_. Use it to fetch, reconnect, or cancel the turn.
​
instance_id
string
The instance that ran the turn.
​
session_id
string
The conversation this turn belongs to. Reuse it on the next call to continue the thread.
​
status
string
in_progress, then a terminal completed, failed, or cancelled.
​
output_text
string
The agent’s final answer.
​
usage
object
Token counts and cost for the turn, e.g. { input_tokens, output_tokens, cost_usd }.

​
Example

curl https://api.agent37.com/v1/responses \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_x7",
    "input": "Find 3 suppliers and email them.",
    "model": "claude-sonnet",
    "provider": "anthropic",
    "stream": false
  }'
Set stream: true to receive Server-Sent Events as the agent reasons, calls tools, and writes its answer. The terminal event carries the final usage.

​
Continue a conversation

The first message names an instance_id and starts a session. The reply returns a session_id; pass it on the next message to continue the same thread. The session holds the full history, so you never resend a transcript: you send only the new input. 
# 1. start a session: name the instance
curl https://api.agent37.com/v1/responses \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_x7",
    "input": "Research the top 3 EV makers, write a memo."
  }'
# -> { "id": "resp_9f2a", "session_id": "sess_1", "status": "completed", ... }

# 2. continue it: reuse the session_id, send only the new input
curl https://api.agent37.com/v1/responses \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_1",
    "input": "Make it shorter, add a quote."
  }'
One active turn per session. A session runs one response at a time. Sending new input while one is in flight returns 409 session_busy. Use another session, or cancel the running turn first.

​
Manage conversations

A session is one conversation on an instance. The instance holds the full history, and one instance can hold many sessions, one per thread. Use these to list a user’s threads, read a thread’s history, or delete one.
ActionEndpoint
List on an instanceGET /v1/instances/{id}/sessions
Retrieve, with historyGET /v1/sessions/{id}
DeleteDELETE /v1/sessions/{id}
Models available to the agentGET /v1/models
GET /v1/instances/{id}/sessions lists every session on an instance. GET /v1/sessions/{id} returns one session with its full history.
​
id
string
The session id, prefixed sess_.
​
instance_id
string
The instance this conversation runs on.
​
agent
string
Which agent the session runs, fixed once the first message starts it.
​
history
array
Every turn in the conversation, in order. You never resend it.

​
Models available to the agent

GET /v1/models lists the models an instance’s agent can run on. Pass any of them as model (with its provider) when you send a message; omit it to use the session’s current model.
DELETE /v1/sessions/{id} is permanent. It removes the conversation and its history but leaves the instance (its files, connected accounts, and memory) untouched.

​
Follow up on a response

Every response has an id you can use after the call returns.
ActionEndpoint
Fetch it againGET /v1/responses/{id}
Reconnect a dropped streamGET /v1/responses/{id}/stream
Stop a running turnPOST /v1/responses/{id}/cancel
GET /v1/responses/{id}/stream replays a snapshot of everything so far, then resumes live, so a dropped connection never loses the answer.
POST /v1/responses/{id}/cancel stops a running turn immediately. Whatever the agent has already done (files written, emails sent, tools called) is not undone. The response ends with status: "cancelled".

​
Status values

A response moves from in_progress to exactly one terminal status.
StatusMeaning
in_progressThe turn is running.
completedThe turn finished and output_text holds the answer.
failedThe turn ended on an error.
cancelledYou stopped the turn with cancel.

​
Next steps

Streaming events

The full event list and a client parser for stream: true.

Instances

Create, size, and manage the computer a conversation runs on.

Core concepts

Instances, sessions, and responses, and why the agent is not the model.

Build a chat app

Put send, continue, and list together into a working chat.