Code Sessions

Create and drive a coding assistant in a workspace's terminal. Each session exposes a terminal you can send input to and poll output from, and can be deployed as an application when the project is ready.

All endpoints require authentication via X-API-Key header and the appropriate scope.

Code Session Object

{
  "_id": "cs_abc123",
  "userId": "user_456",
  "organizationId": "org_xyz",
  "workspaceId": "ws_abc123",
  "projectId": "proj_abc123",
  "managedWorkspace": true,
  "assistant": "claude-code",
  "status": "ready",
  "projectName": "marketing-site",
  "projectDescription": "Static marketing landing page with blog",
  "outputBuffer": [
    { "seq": 1, "type": "stdout", "content": "Welcome to Claude Code", "timestamp": "2025-02-01T14:24:00Z" }
  ],
  "lastSeq": 1,
  "createdAt": "2025-02-01T14:22:00Z",
  "updatedAt": "2025-02-01T14:25:00Z"
}

status is provisioning, ready, active, completed or error (error then says why). While provisioning, provisioningDetail and provisioningStep describe the current step.
managedWorkspace is true when the session created its workspace (ending the session stops it) and false when it runs in a workspace you already had.
assistant is the coding assistant the session drives: claude-code or codex.
outputBuffer holds the terminal output chunks (seq, type of stdout, stderr or system, content, timestamp); lastSeq is the latest chunk's seq.
After a deploy, appId and buildId are set (or deployError if the deploy did not start).

`POST` /api/v1/code-sessions

Create a new code session: a workspace with a terminal you drive over the API.

Scope: code-sessions:write

Request Body

{
  "projectName": "marketing-site",
  "projectDescription": "Static marketing landing page with blog"
}

Field	Type	Required	Description
`projectName`	string	Yes	Name of the project
`projectDescription`	string	Yes	Description of the project

Response 201 Created

The new code session. When a running session for the same project exists, it is resumed instead: 200 OK with that session.

`GET` /api/v1/code-sessions

List your code sessions, most recently updated first. It pages with limit and cursor (Pagination).

Scope: code-sessions:read

Query Parameters

Parameter	Type	Required	Description
`live`	boolean	No	`true` returns only sessions you can resume (`provisioning`, `ready` or `active`). Default: all your sessions

Response 200 OK

{
  "data": [
    {
      "_id": "cs_abc123",
      "userId": "user_456",
      "organizationId": "org_xyz",
      "workspaceId": "ws_abc123",
      "projectId": "proj_abc123",
      "managedWorkspace": true,
      "assistant": "claude-code",
      "status": "ready",
      "projectDescription": "Static marketing landing page with blog",
      "lastSeq": 13,
      "createdAt": "2025-02-01T14:22:00Z",
      "updatedAt": "2025-02-01T14:25:00Z",
      "workspaceName": "marketing-site",
      "workspaceStatus": "running",
      "projectName": "Marketing"
    }
  ],
  "meta": { "total": 1, "limit": 50, "nextCursor": null, "requestId": "req_abc123" }
}

Each entry is a Code Session object without outputBuffer, plus workspaceName and workspaceStatus (the session's workspace). projectName is the name of the project the session belongs to, and is left out for a session with no project. The list is not paginated.

`GET` /api/v1/code-sessions/:id

Get details of a code session including status, workspace info, and metadata.

Scope: code-sessions:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Response 200 OK

Returns the full Code Session object.

{
  "data": {
    "_id": "cs_abc123",
    "userId": "user_456",
    "organizationId": "org_xyz",
    "workspaceId": "ws_abc123",
    "managedWorkspace": true,
    "assistant": "claude-code",
    "status": "ready",
    "projectName": "marketing-site",
    "projectDescription": "Static marketing landing page with blog",
    "outputBuffer": [],
    "lastSeq": 0,
    "createdAt": "2025-02-01T14:22:00Z",
    "updatedAt": "2025-02-01T14:25:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`GET` /api/v1/code-sessions/:id/status

Get the current lifecycle status of a code session. Returns the same record as GET /code-sessions/:id.

Scope: code-sessions:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Response 200 OK

data is the full Code Session object.

Reading a session also brings its status up to date: a provisioning session moves on to ready once its workspace is up, and a ready or active session whose workspace is no longer running moves to error, with error saying why. The same applies to GET /code-sessions/:id.

Errors

Status	Code	When
400	`validation-error`	Invalid session ID
403	`forbidden`	The session belongs to another user (administrators can read any session)
404	`not-found`	No session with this ID

`POST` /api/v1/code-sessions/:id/inputs

Send text input to the code session's PTY (terminal). Use this to execute commands or provide input to a running prompt.

Scope: code-sessions:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Request Body

{
  "text": "ls -la\n"
}

Field	Type	Required	Description
`text`	string	Yes	Text to send to the terminal (include `\n` to submit)

Response 200 OK

{
  "data": {
    "success": true,
    "seq": 11
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`GET` /api/v1/code-sessions/:id/output

Get terminal output from a code session. Use afterSeq to poll for new output since the last read.

Scope: code-sessions:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Query Parameters

Parameter	Type	Required	Description
`afterSeq`	integer	No	Only return output chunks after this sequence number (for polling)

Response 200 OK

{
  "data": {
    "chunks": [
      { "seq": 12, "content": "total 24\n" },
      { "seq": 13, "content": "drwxr-xr-x  5 root root  160 Feb  1 14:25 .\n" }
    ],
    "lastSeq": 13
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`POST` /api/v1/code-sessions/:id/login

Log in to Claude Code in the session's workspace. The platform supplies no Claude credential: you sign in with your own Claude account. This call starts Claude Code in the session's terminal if it is not running yet, starts its login, and returns the sign-in URL. Open the URL, then send the code it shows you to POST /code-sessions/:id/login-codes.

Scope: code-sessions:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Response 200 OK

{
  "data": {
    "authUrl": "https://...",
    "alreadyAuthenticated": false
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

data takes one of these shapes:

Shape	Meaning
`{ "authUrl": "<url>", "alreadyAuthenticated": false }`	Open `authUrl` to sign in. Calling again while that login is in progress returns the same URL
`{ "alreadyAuthenticated": true, "authUrl": null, "note": "..." }`	Claude Code in this workspace is already logged in
`{ "pending": true, "authUrl": null, "message": "..." }`	Claude Code is starting, or login has started but the URL has not appeared yet. Call again in a few seconds
`{ "ready": false, "authUrl": null, "error": "..." }`	The workspace terminal cannot be reached yet (the workspace is still starting). Wait for the session to be `ready`, then call again
`{ "assistant": "codex", "authUrl": null, "useTerminal": true, "message": "..." }`	The session runs Codex, which this call does not log in. Run `codex login` in the terminal with input and read the sign-in URL it prints from output

Errors

Status	Code	When
400	`validation-error`	Invalid session ID
403	`forbidden`	The session belongs to another user (administrators can use any session)
404	`not-found`	No session with this ID

`POST` /api/v1/code-sessions/:id/login-codes

Finish logging in to Claude Code: send the code shown after you signed in at the authUrl from POST /code-sessions/:id/login.

Scope: code-sessions:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Request Body

{
  "code": "abc123def456"
}

Field	Type	Required	Description
`code`	string	Yes	The code shown after signing in

Response 200 OK

{
  "data": {
    "success": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

If login does not succeed, data is { "success": false, "error": "..." }, where error says whether the code was refused (call login again for a fresh URL), the terminal could not be reached (wait for the session to be ready), or login could not be confirmed in time (check the terminal output).

Errors

Status	Code	When
400	`validation-error`	Invalid session ID, or `code` is missing
403	`forbidden`	The session belongs to another user (administrators can use any session)
404	`not-found`	No session with this ID

`POST` /api/v1/code-sessions/:id/deploy

Deploy the code session workspace as an application. Triggers the zip, build, and deploy pipeline.

Scope: code-sessions:deploy

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Response 200 OK

{
  "data": {
    "sessionId": "cs_abc123",
    "appId": "app_def456",
    "buildId": "build_789",
    "status": "building"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`DELETE` /api/v1/code-sessions/:id

End a code session. Stops the workspace and marks the session as completed.

Scope: code-sessions:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Code session ID

Response 204 No Content

Code Session Object​

POST /api/v1/code-sessions​

GET /api/v1/code-sessions​

GET /api/v1/code-sessions/:id​

GET /api/v1/code-sessions/:id/status​

POST /api/v1/code-sessions/:id/inputs​

GET /api/v1/code-sessions/:id/output​

POST /api/v1/code-sessions/:id/login​

POST /api/v1/code-sessions/:id/login-codes​

POST /api/v1/code-sessions/:id/deploy​

DELETE /api/v1/code-sessions/:id​

Code Session Object

`POST` /api/v1/code-sessions

`GET` /api/v1/code-sessions

`GET` /api/v1/code-sessions/:id

`GET` /api/v1/code-sessions/:id/status

`POST` /api/v1/code-sessions/:id/inputs

`GET` /api/v1/code-sessions/:id/output

`POST` /api/v1/code-sessions/:id/login

`POST` /api/v1/code-sessions/:id/login-codes

`POST` /api/v1/code-sessions/:id/deploy

`DELETE` /api/v1/code-sessions/:id