Skip to content
OpenBot

sessions.startTurn

POST
/v1/sessions/{sessionId}/turns
curl --request POST \
  --url https://example.com/v1/sessions/example/turns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "expected": 1, "overrides": { "mode": "default", "model": { "_tag": "Config.Selection", "provider": "example", "model": "example", "reasoningEffort": "example", "serviceTier": "example" } }, "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "example" } ] } ], "background": true, "stream": true }'

Accepts text input and returns an in_progress response. The host scope owns the execution. Read the Session’s response for results. Unsupported fields or input types return 400.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
sessionId
required
string
>= 1 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
expected
required
integer
<= 9007199254740991
overrides
object
mode
string
Allowed values: default plan
model
object
_tag
required
string
Allowed values: Config.Selection
provider
required
string
model
required
string
reasoningEffort
Any of:
string
serviceTier
Any of:
string
input
required
Any of:
string
>= 1 characters
background
boolean
stream
boolean

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typetext/event-stream
object
id
Any of:
string
event
required
string
Allowed values: response.created response.in_progress response.output_item.added response.content_part.added response.output_text.delta response.output_text.done response.content_part.done response.output_item.done response.completed response.incomplete response.failed response.cancelled
data
required
string

202

Section titled “202”

Success

Media typeapplication/json
object
usage
object
inputTokens
required
object
total
integer
>= -9007199254740991 <= 9007199254740991
uncached
integer
>= -9007199254740991 <= 9007199254740991
cacheRead
integer
>= -9007199254740991 <= 9007199254740991
cacheWrite
integer
>= -9007199254740991 <= 9007199254740991
outputTokens
required
object
total
integer
>= -9007199254740991 <= 9007199254740991
text
integer
>= -9007199254740991 <= 9007199254740991
reasoning
integer
>= -9007199254740991 <= 9007199254740991
id
required
string
object
required
string
Allowed values: response
created_at
required
integer
<= 9007199254740991
session
required
string
version
required
string
background
required
boolean
status
required
string
Allowed values: in_progress completed incomplete failed cancelled
output
required
Array<object>
object
id
required
string
type
required
string
Allowed values: message
role
required
string
Allowed values: assistant
status
required
string
Allowed values: in_progress completed incomplete
content
required
Array<object>
object
type
required
string
Allowed values: output_text
text
required
string
annotations
required
array
error
required
Any of:
object
code
required
string
Allowed values: model_error internal_error
message
required
string
incomplete_details
required
Any of:
object
reason
required
string
Allowed values: max_output_tokens content_filter other

Example 

{
  "object": "response",
  "background": true,
  "status": "in_progress",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "in_progress",
      "content": [
        {
          "type": "output_text"
        }
      ]
    }
  ],
  "error": {
    "code": "model_error"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  }
}

400

Section titled “400”

SessionInvalidRecord | SessionModelInvalid | OrganizationRequired

Media typeapplication/json
Any of:
object
_tag
required
string
Allowed values: SessionInvalidRecord
message
required
string

Example 

{
  "_tag": "SessionInvalidRecord"
}

401

Section titled “401”

AuthenticationRequired

Media typeapplication/json
object
_tag
required
string
Allowed values: AuthenticationRequired

Example 

{
  "_tag": "AuthenticationRequired"
}

403

Section titled “403”

PermissionDenied | MembershipRequired | ForbiddenOrigin

Media typeapplication/json
Any of:
object
_tag
required
string
Allowed values: PermissionDenied
permission
required
string
Allowed values: responses.run sessions.read sessions.write requests.resolve agents.read agents.write agents.delegate connections.read connections.write apps.use apps.publish models.use tokens.read tokens.write organization.read organization.write roles.write model_providers.read model_providers.write sso.read sso.write platform.read platform.write members.read members.write audit_logs.read
resource
required
string

Example 

{
  "_tag": "PermissionDenied",
  "permission": "responses.run"
}

404

Section titled “404”

SessionNotFound

Media typeapplication/json
object
_tag
required
string
Allowed values: SessionNotFound
session
required
string

Example 

{
  "_tag": "SessionNotFound"
}

409

Section titled “409”

SessionBusy | SessionConflict

Media typeapplication/json
Any of:
object
_tag
required
string
Allowed values: SessionBusy
session
required
string

Example 

{
  "_tag": "SessionBusy"
}

503

Section titled “503”

SessionStorageUnavailable | SessionExecutionUnavailable | AuthorizationUnavailable | AuthenticationUnavailable

Media typeapplication/json
Any of:
object
_tag
required
string
Allowed values: SessionStorageUnavailable

Example 

{
  "_tag": "SessionStorageUnavailable"
}