Skip to content
OpenBot

sessions.updateSessionSettings

PUT
/v1/sessions/{sessionId}/settings
curl --request PUT \
  --url https://example.com/v1/sessions/example/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "expected": 1, "settings": { "mode": "default", "model": { "_tag": "Config.Selection", "provider": "example", "model": "example", "reasoningEffort": "example", "serviceTier": "example" } } }'

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
settings
required
object
mode
required
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

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
session
required
object
id
required
string
revision
required
integer
<= 9007199254740991
head
required
string
metadata
required
object
title
required
string
archived
required
boolean
settings
required
object
mode
required
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
pending
required
Array<object>
object
id
required
string
content
required
kind
required
string
Allowed values: message steer action
turn
string
action
object
name
required
string
>= 1 characters
arguments
required
object
source
object
turns
required
Array<object>
object
id
required
string
session
required
string
settings
required
object
mode
required
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
action
object
name
required
string
>= 1 characters
arguments
required
object
source
object
activeAction
object
item
required
string
action
required
object
name
required
string
>= 1 characters
arguments
required
object
source
object
status
required
Any of:
object
_tag
required
string
Allowed values: Running
steps
required
integer
<= 9007199254740991
usage
Array<object>
object
inputTokens
required
object
uncached
Any of:
integer
>= -9007199254740991 <= 9007199254740991
total
Any of:
integer
>= -9007199254740991 <= 9007199254740991
cacheRead
Any of:
integer
>= -9007199254740991 <= 9007199254740991
cacheWrite
Any of:
integer
>= -9007199254740991 <= 9007199254740991
outputTokens
required
object
total
Any of:
integer
>= -9007199254740991 <= 9007199254740991
text
Any of:
integer
>= -9007199254740991 <= 9007199254740991
reasoning
Any of:
integer
>= -9007199254740991 <= 9007199254740991
input
required
Array<string>
items
required
Array<string>
start
required
string
end
string
startedAt
required
number
completedAt
number
inheritedTurns
required
Array<object>
object
id
required
string
session
required
string
settings
required
object
mode
required
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
action
object
name
required
string
>= 1 characters
arguments
required
object
source
object
activeAction
object
item
required
string
action
required
object
name
required
string
>= 1 characters
arguments
required
object
source
object
status
required
Any of:
object
_tag
required
string
Allowed values: Running
steps
required
integer
<= 9007199254740991
usage
Array<object>
object
inputTokens
required
object
uncached
Any of:
integer
>= -9007199254740991 <= 9007199254740991
total
Any of:
integer
>= -9007199254740991 <= 9007199254740991
cacheRead
Any of:
integer
>= -9007199254740991 <= 9007199254740991
cacheWrite
Any of:
integer
>= -9007199254740991 <= 9007199254740991
outputTokens
required
object
total
Any of:
integer
>= -9007199254740991 <= 9007199254740991
text
Any of:
integer
>= -9007199254740991 <= 9007199254740991
reasoning
Any of:
integer
>= -9007199254740991 <= 9007199254740991
input
required
Array<string>
items
required
Array<string>
start
required
string
end
string
startedAt
required
number
completedAt
number
business
required
object
forkedFrom
object
session
required
string
version
required
string
state
required
object
version
required
object
id
required
string
schemaVersion
required
string
parents
required
Any of:
array
value
required
object
conversation
required
object
history
required
Array<object>
object
id
required
string
content
required
origin
object
session
required
string
turn
required
string
step
required
integer
<= 9007199254740991
context
required
Any of:
object
_tag
required
string
Allowed values: Prompt
prompt
required
closed
required
boolean
agent
required
string
>= 1 characters <= 128 characters
kind
required
string
Allowed values: direct delegated review
parent
required
Any of:
object
session
required
string
turn
required
string
toolCallId
required
string
response
required
Any of:
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
activity
string
Allowed values: active inactive historical

Example 

{
  "session": {
    "settings": {
      "mode": "default",
      "model": {
        "_tag": "Config.Selection"
      }
    },
    "pending": [
      {
        "kind": "message"
      }
    ],
    "turns": [
      {
        "settings": {
          "mode": "default",
          "model": {
            "_tag": "Config.Selection"
          }
        },
        "status": {
          "_tag": "Running"
        }
      }
    ],
    "inheritedTurns": [
      {
        "settings": {
          "mode": "default",
          "model": {
            "_tag": "Config.Selection"
          }
        },
        "status": {
          "_tag": "Running"
        }
      }
    ]
  },
  "state": {
    "value": {
      "conversation": {
        "context": {
          "_tag": "Prompt"
        }
      }
    }
  },
  "kind": "direct",
  "response": {
    "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"
    }
  },
  "activity": "active"
}

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 | AuthorizationUnavailable | AuthenticationUnavailable

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

Example 

{
  "_tag": "SessionStorageUnavailable"
}