Create Session

Open a conversation with its first message. The context named in the request is attached before the agent runs; the reply arrives on the returned initial_turn operation, which Prefer: wait=N waits for. If that turn fails the session and the message stay — retry with send_session_message. Requires the write scope.

Authorization

apiKey

AuthorizationBearer <token>

First-party API key (sbk_live_…), presented as a Bearer token.

In: header

Path Parameters

project_id*Project Id

Formatuuid

Header Parameters

Idempotency-Key?|

Optional. Repeating a request with the same key returns what it already created (200) instead of running it again.

Prefer?|

RFC 7240. wait=N (N ≤ 60) holds the response until the operation is terminal or N seconds passed: 200 with the finished operation, or the same 202 as without it. respond-async (the default) returns the queued operation at once.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A session is created by its first message; there is no empty session. The reply arrives on the returned initial_turn operation.

text*Text

Length1 <= length <= 20000

title?|null

context?array<>

Itemsitems <= 20

file_ids?array<>

Uploaded files the first message refers to.

Itemsitems <= 20

Default[]

model?|null

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/sessions" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "slug": "string",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "title": "string",  "status": "string",  "pinned": false,  "model": "string",  "turn_count": 0,  "last_message_preview": "string",  "context": [],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "last_activity_at": "2019-08-24T14:15:22Z",  "initial_turn": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "kind": "scene_step",    "status": "queued",    "target": {      "type": "scene",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"    },    "input": {},    "progress": {},    "result": {},    "error": {      "code": "string",      "message": "string",      "retryable": false    },    "credits_charged": 0,    "model": {      "id": "string",      "hosting": "scenebrew",      "billing": "credits"    },    "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",    "created_at": "2019-08-24T14:15:22Z",    "started_at": "2019-08-24T14:15:22Z",    "finished_at": "2019-08-24T14:15:22Z",    "cancel_requested_at": "2019-08-24T14:15:22Z"  }}