Create a session

Create a conversation using the harness supplied at Brain startup. Supply the model credential and the tools this session may use.

POST/v1/sessions

Authorization

serverToken

AuthorizationBearer <token>

The server's BRAIN_API_TOKEN, sent as Authorization: Bearer . Required for application API calls when configured; optional only on a loopback server started without a token.

In: header

Header Parameters

Idempotency-Key*string

Length1 <= length <= 256

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentloop*

Select a startup-registered implementation and supply its session configuration.

environments*array<||>

The Environments of this session, set up as part of this create. Every Tool placement names one of them. The harness is deployment-owned.

idle_ttl_ms?integer

How long the session may sit idle before Brain suspends it: its task and memory are released and rebuilt from disk on the next request. Absent means the server's default; zero means never.

Formatuint64

Range0 <= value

model*

response_format?unknown

The provider's structured-output request, applied to every model call unless the loop sends its own. Optional, and rejected at create for a provider that cannot carry it.

system?string

The system prompt the agent loop starts from. The loop may send a different one on any model call.

Default""

tools*array<>

transcript?array<>

A transcript to carry forward, if the caller has one: the messages the new session's first model call should already see. Brain journals them as the session's opening transcript. Empty is an ordinary new session.

Response Body

`application/json`

curl -X POST "https://example.com/v1/sessions" \  -H "Idempotency-Key: string" \  -H "Authorization: Bearer YOUR_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "agentloop": {      "configuration": {},      "name": "pi"    },    "environments": [      {        "configuration": {},        "driver": "brain",        "lifecycle": "automatic",        "name": "brain"      }    ],    "model": {      "api_key": "YOUR_MODEL_API_KEY",      "name": "gpt-4.1-mini",      "provider": "openai"    },    "tools": []  }'

{  "last_sequence": 0,  "session_id": "string",  "status": "creating"}

Create a session

Authorization

Header Parameters

Request Body

Response Body

200application/json

defaultapplication/json

`application/json`

`application/json`