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,
small,
medium,
large,
xl,
xxl,
ultra
targetBranch
string | null

Default target branch for pull requests created by the session.

Required string length: 1 - 500
visibility
enum<string>

Session visibility: private or visible to workspace (public).

Available options:
private,
public
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
id
string<uuid>

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

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.

queueRightAway
boolean

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

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

Response

Create a session

agent
string | null
required
agentId
string<uuid> | null
required
artifactType
enum<string> | null
required
Available options:
PullRequest,
ToolCall,
Plan,
Response,
File,
Service,
Source,
null
baseBranch
string | null
required
branchName
string | null
required
createdAt
string<date-time>
required
externalId
string | null
required
externalUrl
string | null
required
id
string<uuid>
required
kind
string
required
lastQueuedAt
string<date-time> | null
required
lastSeenAt
string<date-time>
required
level
integer
required
mode
enum<string>
default:normal
required
Available options:
normal,
planning
projectId
string | null
required
sandboxSize
enum<string> | null
required
Available options:
nano,
micro,
small,
medium,
large,
xl,
xxl,
ultra,
null
sessionType
enum<string>
default:Chat
required
Available options:
Chat,
Terminal
targetBranch
string | null
required
title
string
required
updatedAt
string<date-time>
required
visibility
enum<string>
default:public
required
Available options:
public,
private
artifacts
object[]
required
description
string | null
required
diffSummary
object | null
required
htmlUrl
string<uri>
required
isPinned
boolean
required
project
object | null
required
sessionSource
object
required
sourcePullRequest
object | null
required
state
object
required