Create Session

curl --request POST \
  --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "environment_id": "3c2a1f80-7e64-4b19-8d55-11aa22bb33cc",
  "max_turns": 20,
  "pacing": "pause_on_decide",
  "person_id": "9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234",
  "reasoning_effort": "low",
  "task": {
    "instructions": "Find the refund policy and start a return."
  }
}
'

import requests

url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions"

payload = {
    "environment_id": "3c2a1f80-7e64-4b19-8d55-11aa22bb33cc",
    "max_turns": 20,
    "pacing": "pause_on_decide",
    "person_id": "9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234",
    "reasoning_effort": "low",
    "task": { "instructions": "Find the refund policy and start a return." }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    environment_id: '3c2a1f80-7e64-4b19-8d55-11aa22bb33cc',
    max_turns: 20,
    pacing: 'pause_on_decide',
    person_id: '9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234',
    reasoning_effort: 'low',
    task: {instructions: 'Find the refund policy and start a return.'}
  })
};

fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'environment_id' => '3c2a1f80-7e64-4b19-8d55-11aa22bb33cc',
    'max_turns' => 20,
    'pacing' => 'pause_on_decide',
    'person_id' => '9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234',
    'reasoning_effort' => 'low',
    'task' => [
        'instructions' => 'Find the refund policy and start a return.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions"

	payload := strings.NewReader("{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "accrued_credits": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_api_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "decision_mode": "direct",
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "environment": {
    "kind": "<string>",
    "name": "<string>"
  },
  "environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_revision": 123,
  "environment_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_version_label": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_turns": 123,
  "status": "open",
  "task": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "instructions": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "turn_count": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "observation_retention": "<string>",
  "pacing": "pause_on_decide",
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "person_snapshot": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "snapshotted_at": "2023-11-07T05:31:56Z",
    "type": "ai",
    "avatar_url": "<string>",
    "bio": "<string>",
    "city": "<string>",
    "country": "<string>",
    "date_of_birth": "2023-12-25",
    "education_level": "less_than_secondary",
    "employment_status": "employed_full_time",
    "gender": "male",
    "household": "single",
    "income_level": "lower",
    "interests": [
      "<string>"
    ],
    "languages": [
      "<string>"
    ],
    "locale_type": "urban",
    "occupation": "<string>",
    "snapshot_version": "2",
    "timezone": "<string>"
  },
  "reasoning_effort": "<string>",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "accrued_credits": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_api_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "decision_mode": "direct",
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "environment": {
    "kind": "<string>",
    "name": "<string>"
  },
  "environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_revision": 123,
  "environment_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_version_label": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_turns": 123,
  "status": "open",
  "task": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "instructions": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "turn_count": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "observation_retention": "<string>",
  "pacing": "pause_on_decide",
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "person_snapshot": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "snapshotted_at": "2023-11-07T05:31:56Z",
    "type": "ai",
    "avatar_url": "<string>",
    "bio": "<string>",
    "city": "<string>",
    "country": "<string>",
    "date_of_birth": "2023-12-25",
    "education_level": "less_than_secondary",
    "employment_status": "employed_full_time",
    "gender": "male",
    "household": "single",
    "income_level": "lower",
    "interests": [
      "<string>"
    ],
    "languages": [
      "<string>"
    ],
    "locale_type": "urban",
    "occupation": "<string>",
    "snapshot_version": "2",
    "timezone": "<string>"
  },
  "reasoning_effort": "<string>",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "errors": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "allowed_values": [
        "<unknown>"
      ],
      "input": "<string>"
    }
  ],
  "retryable": true,
  "status": 123,
  "suggestions": [
    "<string>"
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

API reference

Create Session

Open a session: one of your people, working toward one task, inside your environment.

The TASK is required and is exactly one of two shapes: {"instructions": "..."} describes the intent inline, or {"id": "..."} binds a task you registered. A bound task’s instructions are frozen onto the session, so later edits to the registry never change a run that already happened. An id that does not resolve is a 404; one that resolves but is retired is a 409.

The ENVIRONMENT is also exactly one of two shapes: environment_id names one you registered, or environment describes an ad-hoc one inline. A registered environment’s name, kind and configuration are snapshot onto the session for the same reason.

Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original session as a 200, and the same key with a different body is a 409.

POST

api

workspaces

{workspace_id}

sessions

Create Session

curl --request POST \
  --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "environment_id": "3c2a1f80-7e64-4b19-8d55-11aa22bb33cc",
  "max_turns": 20,
  "pacing": "pause_on_decide",
  "person_id": "9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234",
  "reasoning_effort": "low",
  "task": {
    "instructions": "Find the refund policy and start a return."
  }
}
'

import requests

url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions"

payload = {
    "environment_id": "3c2a1f80-7e64-4b19-8d55-11aa22bb33cc",
    "max_turns": 20,
    "pacing": "pause_on_decide",
    "person_id": "9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234",
    "reasoning_effort": "low",
    "task": { "instructions": "Find the refund policy and start a return." }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    environment_id: '3c2a1f80-7e64-4b19-8d55-11aa22bb33cc',
    max_turns: 20,
    pacing: 'pause_on_decide',
    person_id: '9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234',
    reasoning_effort: 'low',
    task: {instructions: 'Find the refund policy and start a return.'}
  })
};

fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'environment_id' => '3c2a1f80-7e64-4b19-8d55-11aa22bb33cc',
    'max_turns' => 20,
    'pacing' => 'pause_on_decide',
    'person_id' => '9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234',
    'reasoning_effort' => 'low',
    'task' => [
        'instructions' => 'Find the refund policy and start a return.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions"

	payload := strings.NewReader("{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"environment_id\": \"3c2a1f80-7e64-4b19-8d55-11aa22bb33cc\",\n  \"max_turns\": 20,\n  \"pacing\": \"pause_on_decide\",\n  \"person_id\": \"9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234\",\n  \"reasoning_effort\": \"low\",\n  \"task\": {\n    \"instructions\": \"Find the refund policy and start a return.\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "accrued_credits": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_api_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "decision_mode": "direct",
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "environment": {
    "kind": "<string>",
    "name": "<string>"
  },
  "environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_revision": 123,
  "environment_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_version_label": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_turns": 123,
  "status": "open",
  "task": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "instructions": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "turn_count": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "observation_retention": "<string>",
  "pacing": "pause_on_decide",
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "person_snapshot": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "snapshotted_at": "2023-11-07T05:31:56Z",
    "type": "ai",
    "avatar_url": "<string>",
    "bio": "<string>",
    "city": "<string>",
    "country": "<string>",
    "date_of_birth": "2023-12-25",
    "education_level": "less_than_secondary",
    "employment_status": "employed_full_time",
    "gender": "male",
    "household": "single",
    "income_level": "lower",
    "interests": [
      "<string>"
    ],
    "languages": [
      "<string>"
    ],
    "locale_type": "urban",
    "occupation": "<string>",
    "snapshot_version": "2",
    "timezone": "<string>"
  },
  "reasoning_effort": "<string>",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "accrued_credits": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "created_by_api_key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "decision_mode": "direct",
  "ended_at": "2023-11-07T05:31:56Z",
  "ended_reason": "<string>",
  "environment": {
    "kind": "<string>",
    "name": "<string>"
  },
  "environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_revision": 123,
  "environment_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "environment_version_label": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_turns": 123,
  "status": "open",
  "task": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "instructions": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "turn_count": 123,
  "updated_at": "2023-11-07T05:31:56Z",
  "observation_retention": "<string>",
  "pacing": "pause_on_decide",
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "person_snapshot": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "snapshotted_at": "2023-11-07T05:31:56Z",
    "type": "ai",
    "avatar_url": "<string>",
    "bio": "<string>",
    "city": "<string>",
    "country": "<string>",
    "date_of_birth": "2023-12-25",
    "education_level": "less_than_secondary",
    "employment_status": "employed_full_time",
    "gender": "male",
    "household": "single",
    "income_level": "lower",
    "interests": [
      "<string>"
    ],
    "languages": [
      "<string>"
    ],
    "locale_type": "urban",
    "occupation": "<string>",
    "snapshot_version": "2",
    "timezone": "<string>"
  },
  "reasoning_effort": "<string>",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "errors": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "allowed_values": [
        "<unknown>"
      ],
      "input": "<string>"
    }
  ],
  "retryable": true,
  "status": 123,
  "suggestions": [
    "<string>"
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

Authorizations

Authorization

string

header

required

Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.

Headers

Idempotency-Key

string | null

Path Parameters

workspace_id

string<uuid>

required

Body

application/json

pacing

enum<string>

required

Available options:

pause_on_decide,

frame_on_demand,

free_running

person_id

string<uuid>

required

task

TaskRef · object

required

A registered task in this workspace, bound by id.

TaskRef
TaskDescriptor

Show child attributes

decision_mode

enum<string>

default:intent

Available options:

direct,

intent

environment

EnvironmentDescriptor · object | null

An ad-hoc environment described inline. Mutually exclusive with environment_id; supply exactly one.

Show child attributes

environment_id

string<uuid> | null

A registered environment in this workspace. Mutually exclusive with environment; supply exactly one.

environment_version

string | null

Pin this session to a declared version of the registered environment, by label (case-insensitive; the canonical label is recorded). Requires environment_id. Omit to use the environment's default version, or to run unversioned when it has none. An unknown label is a 404, never a new bucket.

Required string length: 1 - 120

max_turns

integer

default:50

Required range: 1 <= x <= 200

observation_retention

enum<string> | null

How long this session's observation frames are retained: none (discard after the turn), 30d, 90d, or indefinite. Omit to inherit the registered environment's setting; an inline environment descriptor defaults to none. Resolved once at open and fixed for the session's lifetime. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

Available options:

none,

30d,

90d,

indefinite

reasoning_effort

enum<string>

default:low

Available options:

low,

medium,

high

resolver_guidance

string | null

Maximum string length: 8000

Response

Idempotent replay: an existing session was returned because the Idempotency-Key and request body matched a prior create.

The full session, without its decision trace.

What create and close return: a caller that opened a session holds the same object a read would give it, so nothing has to be fetched twice to learn what was actually frozen. The TRACE is deliberately absent: turns are a paged subresource of the detail read, and a create has none yet.

accrued_credits

integer

required

This session's spend in credits (0 if it had no billable turns).

created_at

string<date-time>

required

created_by_api_key_id

string<uuid> | null

required

decision_mode

enum<string>

required

Available options:

direct,

intent

ended_at

string<date-time> | null

required

When the session left open (UTC), stamped on the first terminal transition and never moved. Null while the session is open. This is the timestamp sessions_ended usage buckets on.

ended_reason

string | null

required

Why the session ended, when that is finer than status: credits_exhausted or plan_allowance_exhausted (both end the session as balance_exhausted), or spend_cap_reached. Null for an ordinary ending. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

environment

EnvironmentDescriptor · object

required

The environment as frozen at create (name + kind snapshot).

Show child attributes

environment_id

string<uuid> | null

required

environment_revision

integer | null

required

environment_version_id

string<uuid> | null

required

environment_version_label

string | null

required

string<uuid>

required

max_turns

integer

required

status

enum<string>

required

Session status. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

Available options:

open,

completed,

gave_up,

closed,

max_turns,

spend_cap_reached,

balance_exhausted

task

TaskSnapshot · object

required

The session's intent, frozen when it was created. A later edit to a registered task never changes it.

Show child attributes

turn_count

integer

required

updated_at

string<date-time>

required

observation_retention

string

required

Retention window resolved at open: none, 30d, 90d, or indefinite. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

pacing

enum<string>

required

Available options:

pause_on_decide,

frame_on_demand,

free_running

person_id

string<uuid> | null

required

person_snapshot

PersonSnapshot · object

required

The person as they were when the session was created, frozen onto the session.

This, not the live person, is what the session was run against: it stays readable and unchanged after the person is edited or deleted, which is what makes an old trace still mean something. id is the person's id at create time.

Additional keys may be present and more may be added over time; treat anything not listed here as unspecified rather than failing on it.

Show child attributes

reasoning_effort

string

required

Deliberation budget the session was opened with: low, medium or high. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

workspace_id

string<uuid>

required

Get started

Core concepts

Guides

API reference

Versioning and changes

Create Session

Authorizations

Headers

Path Parameters

Body

Response