Open a session for a principal

POST

/sessions

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" }, "inference": "example", "instructions": "example", "params": { "effort": "low", "max_tokens": 1, "stop": [ "example" ], "temperature": 1, "top_p": 1 }, "rounds": 1 }'

Authorizations

• install_key

Parameters

Query Parameters

principal

required

string

The install’s own name for the user this session is for.

Request Body^required

Media typeapplication/json

What the caller supplies for this session: instructions, generation settings, the preset it runs on, and the executor implementing the vendor’s tools.

object

executor

One of:

null

null

object

The executor the caller brings on dial. It tails the session to read execution requests and appends their fulfilment; the tools are its own.

object

name

required

string

public_key

required

string

inference

One of:

null

null

string

The consented preset this session runs on; absent, the install’s default.

string

instructions

string

params

object

effort

One of:

null

null

string

Absent on every record written before this field existed, and absent from the wire when the caller asks for no particular effort.

string

Allowed values: low medium high xhigh max

max_tokens

integer | null format: int64

stop

Array<string>

temperature

number | null format: double

top_p

number | null format: double

rounds

integer format: int32

Responses

200

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"
}

400

No principal, or an invalid body; the response names the invalid field when available.

401

No install key, or one no install answers.

403

The dial names an inference option the install did not consent to: {"error": "inference_not_allowed", "inference": <id>}. Nothing lands.

404

The install the key names is gone.

409

A connected MCP catalog changed.

502

A connected MCP catalog could not be read.