sessions_create
POST
/sessions
const url = 'https://api.canopyhq.dev/sessions?principal=example';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"executor":{"name":"example","public_key":"example"},"instructions":"example","params":{"max_tokens":1,"stop":["example"],"temperature":1,"top_p":1},"rounds":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.canopyhq.dev/sessions?principal=example' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "executor": { "name": "example", "public_key": "example" }, "instructions": "example", "params": { "max_tokens": 1, "stop": [ "example" ], "temperature": 1, "top_p": 1 }, "rounds": 1 }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”principal
required
string
The install’s own name for the user this session is for.
Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
What the caller supplies for this session: instructions, generation settings, and the executor implementing the vendor’s tools.
object
executor
instructions
string
params
object
max_tokens
integer | null format: int64
stop
Array<string>
temperature
number | null format: double
top_p
number | null format: double
rounds
integer format: int32
Examplegenerated
{ "executor": { "name": "example", "public_key": "example" }, "instructions": "example", "params": { "max_tokens": 1, "stop": [ "example" ], "temperature": 1, "top_p": 1 }, "rounds": 1}Responses
Section titled “Responses”The new session and a token that attaches to it.
Media typeapplication/json
object
expires
required
integer format: int64
session
required
A stream id: 72 hex chars, the shard then the owner digest.
string
token
required
string
Example
{ "session": "000000000000000000000000000000000000000000000000000000000000000000000000"}No principal, or an invalid body; the response names the invalid field when available.
No install key, or one no install answers.
The install the key names is gone.
A connected MCP catalog changed.
A connected MCP catalog could not be read.