Skip to main content
PATCH
TypeScript SDK

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sessionId
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json
visibility
enum<string>
deprecated

Deprecated, kept until older clients update; share the session instead. public shares it with the workspace; private removes every share so only the creator reaches it. Only the session creator can change it.

Available options:
private,
public
memoryMb
integer

Request in-place memory growth for a running adaptive sandbox, within project limits. Submit separately from other session changes. Returns the session while the resize runs asynchronously; sandbox metrics report its progress.

Required range: 1024 <= x <= 131072Must be a multiple of 1024
agent
string | null

Change the agent and model key. Null clears the session override.

Required string length: 1 - 500
agentOptions
object

Change agent-specific runtime options, such as reasoning effort.

baseBranch
string | null

Change the starting Git branch. Null clears the session override.

Required string length: 1 - 500
branchName
string | null

Change the session Git branch name. Null clears the stored name.

Required string length: 1 - 500
description
string

Replace the initial task prompt; only the session creator can change it. Use createMessage to send a follow-up task.

Required string length: 1 - 1000000
richContent
object

Replace the initial prompt rich-text document, or null to clear it. Only the session creator can change it.

Example:
level
integer

Archive or restore the session and set its priority: 0 archives and stops its VM; 1 restores without restarting work; 2–100 also keep it unarchived and set its priority level. Omit to preserve the current level.

Required range: 0 <= x <= 100
mcpServers
string[]

Replace the enabled MCP server or connection IDs. An empty array clears the selection.

Maximum array length: 100
Required string length: 1 - 500
mode
enum<string>

Switch between Build (normal) and Plan (planning) modes.

Available options:
normal,
planning
projectId
string | null

Change the project environment used for the workspace. Null clears the session override.

sandboxSize
enum<string> | null

Change the workspace VM size. Null clears the session override.

Available options:
nano,
micro,
medium,
large,
xl,
xxl,
ultra
targetBranch
string | null

Change the default pull request target branch. Null clears the session override.

Required string length: 1 - 500
title
string

Rename the session.

Required string length: 1 - 1000

Response

Update a session

agent
string | null
required
agentId
string<uuid> | null
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
artifactType
enum<string> | null
required
Available options:
PullRequest,
ToolCall,
Plan,
Response,
File,
Service,
Source
baseBranch
string | null
required
branchName
string | null
required
createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
externalId
string | null
required
externalUrl
string | null
required
id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
kind
string
required
lastQueuedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
lastSeenAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
level
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
mode
enum<string>
default:normal
required
Available options:
normal,
planning
parentSessionId
string<uuid> | null
required

The session whose agent created this session.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
projectId
string | null
required
sandboxSize
enum<string> | null
required
Available options:
nano,
micro,
small,
medium,
large,
xl,
xxl,
ultra
sessionType
enum<string>
default:Chat
required
Available options:
Chat,
Terminal
targetBranch
string | null
required
title
string
required
updatedAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
visibility
enum<string>
required
deprecated

Deprecated: private when shared with no one, public when shared with anyone. List the session’s shares for its exact audiences.

Available options:
private,
public
artifacts
object[]
required
automaticSizing
boolean
required

Whether the session VM is sized automatically.

description
string | null
required
diffSummary
object | null
required
folderId
string<uuid> | null
required

Sidebar folder the authenticated user filed this session in.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
htmlUrl
string<uri>
required
isPinned
boolean
required
project
object | null
required
sessionSource
object
required
sourcePullRequest
object | null
required
state
object
required