Skip to main content
POST
Create session
You are reading the docs of Galtea 5.11. Read this page in the latest version.

Authorizations

Authorization
string
header
required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json

Session creation input. versionId is optional: when omitted, provide productId and the API reuses the product's latest version (creating a default first version if the product has none). One of versionId or productId is required. testCaseId and isProduction are independent: a session can be production (no testCaseId), test-driven non-production (testCaseId set, isProduction defaults to false), or externally-ingested non-production (no testCaseId, isProduction explicitly false — typical for imported traces). The only forbidden combination is testCaseId set together with isProduction=true. When testCaseId is set, context is rejected because it would be derived from the test case.

versionId
string

Version ID to create the session for. Optional when productId is provided; one of versionId or productId is required.

Example:

"ver_123"

productId
string

Product to anchor the session when versionId is omitted. The API reuses the product's latest version or creates a default one. Ignored when versionId is provided.

Example:

"prod_123"

customId
string

Optional caller-defined identifier for the session

Example:

"my-session-1"

testCaseId
string

Test case to link this session to. Forbidden when isProduction=true. Defaults to omitted, in which case isProduction defaults to true.

Example:

"tc_123"

isProduction
boolean

Whether the session represents real production traffic. Defaults to true when testCaseId is omitted and false when testCaseId is set. May be set explicitly to false without a testCaseId for externally-ingested sessions (e.g. trace imports).

context

Additional context for the session. Accepts a plain string or a structured JSON object. Forbidden when testCaseId is set (the context is derived from the test case).

metadata
object

Arbitrary key-value metadata

Example:
status
enum<string>
default:PENDING

Initial session status. Defaults to PENDING (open, accepts new turns); the session closes on an explicit finish or the product auto-close sweep (#3384).

Available options:
PENDING,
COMPLETED,
FAILED
runId
string

Run to attribute this session to, so several sessions a client creates are grouped together. It must name a run you opened with POST /runs: a run a platform launch opened settles with that launch and is rejected here, as is a deleted, finished, other-product or other-version run. Forbidden when isProduction is true.

Example:

"run_123"

Response

Session created successfully

id
string
required
Example:

"session_123"

customId
string | null
required
Example:

"custom_session_123"

versionId
string
required
Example:

"ver_123"

userId
string | null
required
Example:

"user_123"

testCaseId
string | null
required
Example:

"tc_123"

context
object | null
required

Structured context data. For plain text context, format is { value: "..." }

Example:
stoppingReason
string | null
required
Example:

"GOAL_ACHIEVED"

recordingUri
string | null
required

Storage URI of the full-call recording for a telephony-evaluation session, returned under STORAGE_PUBLIC_BASE_URL when the deployment configures one. Null for non-telephony sessions or before the recording is processed. Resolve to a playable URL via GET /storage?uri=.

Example:

"https://files.galtea.ai/audio/org_123/session_abc-recording.mp3"

error
string | null
required
Example:

"External API responded with HTTP 422: Unprocessable Entity — {\"detail\":\"model not found\"}"

status
enum<string>
required
Available options:
PENDING,
COMPLETED,
FAILED
Example:

"PENDING"

isProduction
boolean
required

True when the session represents real production traffic (no associated test case).

Example:

false

isSeed
boolean
required
read-only

True when the session holds the predefined conversation of a test case and is never executed. Server-managed and read-only.

Example:

false

runId
string | null
required

The run that created this session. Null for a session created outside a launch (production traffic, an imported trace). A session a run only scored names no run here; filter with involvedInRunIds to reach those too.

Example:

"run_123"

deletedAt
string<date-time> | null
required
metadata
any | null

Arbitrary metadata, returned as stored. Usually an object, but any JSON value is accepted.

Example:
createdAt
string<date-time>