Skip to main content
POST
TypeScript SDK

Authorizations

Authorization
string
header
required

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

Body

application/json
description
string
required

Initial task or prompt for the session.

Required string length: 1 - 1000000
agent
string

Agent and model key to run, such as claudeCode:claude-fable-5-1. Omit to use the default.

Required string length: 1 - 500
baseBranch
string | null

Git branch to start work from. Omit or use null for the repository default.

Required string length: 1 - 500
mcpServers
string[]

MCP server or connection IDs to enable for the session.

Maximum array length: 100
Required string length: 1 - 500
projectId
string | null

Project environment to use for the workspace. Omit or use null for the default.

sandboxSize
enum<string>

VM size for the session workspace.

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

Default target branch for pull requests created by the session.

Required string length: 1 - 500
agentOptions
object

Agent-specific runtime options, such as reasoning effort.

branchName
string | null

Git branch for this session. Omit or use null to generate a branch name.

Required string length: 1 - 500
codeRepositoryIds
string<uuid>[]

Repository IDs to make available in the session workspace.

Maximum array length: 100
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)$
id
string<uuid>

Optional caller-supplied session UUID. Omit to generate one.

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)$
richContent
object

Optional rich-text representation of the initial task. Provide description separately.

Example:
pullRequestId
string<uuid>

Pull request to associate with the session. Requires richContent.

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)$
queueRightAway
boolean

Whether to queue the initial task immediately instead of only creating the session.

automaticSizing
boolean

Size the VM automatically. Sessions are sized automatically by default, and project sessions always are.

sessionMode
enum<string>

Whether to create a chat session or a terminal session.

Available options:
chat,
terminal
startupAgent
enum<string>

Coding agent to start in a terminal session.

Available options:
claudeCode,
codex,
opencode,
pi,
amp,
cursor
visibility
enum<string>

Who starts with access: private, or shared with the workspace (public). Defaults by session source; change it later by sharing.

Available options:
private,
public
teamId
string<uuid>

Also share the new session with this team, in the same transaction that creates it.

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)$

Response

Create 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