API reference

Caity's Code mode

Coding sessions on your own machine, with your own Claude Code or Codex login.

GET/v1/me/code/devices

Your machines approved for Code mode, with the folders each allows (cactive-agent code allow), whether it's online and whether its agent is ready (full network access, a recent agent with room for a session).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Errors

403Code mode is for people, signed in.

curl 'https://api.cactive.com.au/v1/me/code/devices' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  devices: {
    deviceId: string
    orgId: string
    name: string
    platform: null | string
    folders: string[]
    online: boolean
    ready: boolean
  }[]
}

GET/v1/me/code/sessions

Your Code mode sessions, newest first (50).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Errors

403Code mode is for people, signed in.

curl 'https://api.cactive.com.au/v1/me/code/sessions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  sessions: {
    pending: string[]
    error?: string
    userId: string
    status: "canceled" | "failed" | "stopped" | "starting" | "running"
    createdAt: number
    updatedAt?: number
    orgId: string
    sessionId: string
    model?: string
    title?: string
    provider: string
    deviceId: string
    target?: "cloud" | "machine"
    queued?: number
    branch?: string
    buildId?: string
    git?: boolean
    jobId: string
    plan?: boolean
    folder: string
    mode: string
    effort?: string
    working?: boolean
    conversationId?: string
    lastSeq?: number
    turns?: number
    worktree?: string
    endedAt?: number
    repo?: {
      orgId: string
      repoId: string
      name: string
      branch: string
      workBranch: string
    }
    pullRequest?: {
      number: number
      url: string
    }
  }[]
}

POST/v1/me/code/sessions

Starts a Code mode session on one of your own machines, in a folder it allows, with your own Claude Code or Codex login there. mode is at most your mode for the assistant in that machine's space; effort (low to max) and plan (plan mode) are optional; isolation (branch or worktree) with a branch starts it on a new branch or in a worktree of its own inside the folder; 409 when the machine isn't approved for Code mode or lacks full network access. bedrock is Caity herself: the tools run on the machine, each model step through the platform.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Request body

deviceIdstringrequired
Matches ^[A-Za-z0-9_-]{1,80}$.
folderstringrequired
1–1,024 characters.
provider"claude-code" | "codex" | "bedrock" | "fake"required
modelstring
Up to 100 characters. Matches ^[A-Za-z0-9._:/@\[\]-]+$.
mode"ask" | "reads" | "app" | "auto"
effort"low" | "medium" | "high" | "max"
planboolean
titlestring
Up to 200 characters.
conversationIdstring
Matches ^[A-Za-z0-9_-]{1,80}$.
isolation"none" | "branch" | "worktree"
branchstring

Errors

400That folder isn't allowed on that machine. Run cactive-agent code allow <folder> there first.
400Unknown provider.
400The test provider isn't available here.
400A new branch or worktree needs a branch name git takes.
403Code mode isn't available to the phone assistant.
403Caity is off for you in that machine's space.
403Code mode is for people, signed in.
404Device not found
409Code mode isn't approved on that machine. Add it to the device in Cloud → Agents.
409Code mode needs full network access on that machine (its provider talks to its own service).

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "<deviceId>",
    "folder": "example",
    "provider": "claude-code"
  }'

Send it from this page with your session or a key.

Response 201

{
  session: {
    pending: string[]
    error?: string
    userId: string
    status: "canceled" | "failed" | "stopped" | "starting" | "running"
    createdAt: number
    updatedAt?: number
    orgId: string
    sessionId: string
    model?: string
    title?: string
    provider: string
    deviceId: string
    target?: "cloud" | "machine"
    queued?: number
    branch?: string
    buildId?: string
    git?: boolean
    jobId: string
    plan?: boolean
    folder: string
    mode: string
    effort?: string
    working?: boolean
    conversationId?: string
    lastSeq?: number
    turns?: number
    worktree?: string
    endedAt?: number
    repo?: {
      orgId: string
      repoId: string
      name: string
      branch: string
      workBranch: string
    }
    pullRequest?: {
      number: number
      url: string
    }
  }
}

POST/v1/me/code/cloud-sessions

A session in the cloud, on one of the person's organisation's repositories (docs/specs/caity/coding.md → Caity in the cloud).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Request body

orgIdstringrequired
Matches ^[A-Za-z0-9_-]{1,80}$.
repoIdstringrequired
1–100 characters.
branchstringrequired
1–255 characters.
textstring
Up to 32,000 characters. Trimmed.
modelstring
Up to 100 characters. Matches ^[A-Za-z0-9._:/@-]+$.
mode"ask" | "reads" | "app" | "auto"
titlestring
Up to 200 characters.

Errors

403Code mode is for people, signed in.

curl -X POST 'https://api.cactive.com.au/v1/me/code/cloud-sessions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "orgId": "<orgId>",
    "repoId": "<repoId>",
    "branch": "example"
  }'

Send it from this page with your session or a key.

Response 201

{
  session: {
    pending: string[]
    error?: string
    userId: string
    status: "canceled" | "failed" | "stopped" | "starting" | "running"
    createdAt: number
    updatedAt?: number
    orgId: string
    sessionId: string
    model?: string
    title?: string
    provider: string
    deviceId: string
    target?: "cloud" | "machine"
    queued?: number
    branch?: string
    buildId?: string
    git?: boolean
    jobId: string
    plan?: boolean
    folder: string
    mode: string
    effort?: string
    working?: boolean
    conversationId?: string
    lastSeq?: number
    turns?: number
    worktree?: string
    endedAt?: number
    repo?: {
      orgId: string
      repoId: string
      name: string
      branch: string
      workBranch: string
    }
    pullRequest?: {
      number: number
      url: string
    }
  }
}

GET/v1/me/code/sessions/:sessionId

A session: its machine, folder, provider, mode, status, turns and the approvals waiting for you.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

403Code mode is for people, signed in.
404Session not found

curl 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  session: {
    pending: string[]
    error?: string
    userId: string
    status: "canceled" | "failed" | "stopped" | "starting" | "running"
    createdAt: number
    updatedAt?: number
    orgId: string
    sessionId: string
    model?: string
    title?: string
    provider: string
    deviceId: string
    target?: "cloud" | "machine"
    queued?: number
    branch?: string
    buildId?: string
    git?: boolean
    jobId: string
    plan?: boolean
    folder: string
    mode: string
    effort?: string
    working?: boolean
    conversationId?: string
    lastSeq?: number
    turns?: number
    worktree?: string
    endedAt?: number
    repo?: {
      orgId: string
      repoId: string
      name: string
      branch: string
      workBranch: string
    }
    pullRequest?: {
      number: number
      url: string
    }
  }
}

GET/v1/me/code/sessions/:sessionId/events

The session's events after after (their seq), in order, up to 500 (more when there are more): messages, steps, command output, approvals, checkpoints.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Query parameters

afterinteger
≥ 0. Coerced from a string.

Errors

403Code mode is for people, signed in.
404Session not found

curl 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/events' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  session: {
    pending: string[]
    error?: string
    userId: string
    status: "canceled" | "failed" | "stopped" | "starting" | "running"
    createdAt: number
    updatedAt?: number
    orgId: string
    sessionId: string
    model?: string
    title?: string
    provider: string
    deviceId: string
    target?: "cloud" | "machine"
    queued?: number
    branch?: string
    buildId?: string
    git?: boolean
    jobId: string
    plan?: boolean
    folder: string
    mode: string
    effort?: string
    working?: boolean
    conversationId?: string
    lastSeq?: number
    turns?: number
    worktree?: string
    endedAt?: number
    repo?: {
      orgId: string
      repoId: string
      name: string
      branch: string
      workBranch: string
    }
    pullRequest?: {
      number: number
      url: string
    }
  }
  events: {
    type: "session.started"
    provider: "claude-code" | "codex" | "bedrock" | "fake"
    model: null | string
    folder: string
    git: boolean
    mode: "ask" | "reads" | "app" | "auto"
    branch?: string
    worktree?: string
    seq: number
    at: number
  } | {
    type: "turn.started"
    turn: number
    text: string
    commandId: string
    seq: number
    at: number
  } | {
    type: "message.delta"
    turn: number
    text: string
    seq: number
    at: number
  } | {
    type: "message"
    turn: number
    text: string
    seq: number
    at: number
  } | {
    type: "thinking.delta"
    turn: number
    text: string
    seq: number
    at: number
  } | {
    type: "thinking"
    turn: number
    text: string
    seq: number
    at: number
  } | {
    type: "tool.started"
    turn: number
    toolId: string
    kind: "read" | "edit" | "command" | "other"
    title: string
    detail?: string
    name?: string
    input?: {
      tool: "read"
      path: string
      offset?: number
      limit?: number
    } | {
      tool: "edit"
      path: string
      edits: {
        old: string
        new: string
      }[]
      replaceAll?: boolean
    } | {
      tool: "write"
      path: string
      content: string
    } | {
      tool: "patch"
      paths: string[]
      patch: string
    } | {
      tool: "search"
      pattern: string
      path?: string
      glob?: string
    } | {
      tool: "glob"
      pattern: string
      path?: string
    } | {
      tool: "list"
      path: string
    } | {
      tool: "command"
      command: string
      description?: string
      background?: boolean
    } | {
      tool: "todo"
      items: {
        text: string
        status: "pending" | "in_progress" | "completed"
      }[]
    } | {
      tool: "fetch"
      url: string
    } | {
      tool: "websearch"
      query: string
    } | {
      tool: "task"
      description: string
      prompt?: string
    } | {
      tool: "plan"
      plan: string
    } | {
      tool: "other"
      summary?: string
    }
    parentId?: string
    seq: number
    at: number
  } | {
    type: "tool.output"
    turn: number
    toolId: string
    text: string
    seq: number
    at: number
  } | {
    type: "tool.finished"
    turn: number
    toolId: string
    ok: boolean
    exitCode?: number
    summary?: string
    seq: number
    at: number
  } | {
    type: "todos"
    turn: number
    items: {
      text: string
      status: "pending" | "in_progress" | "completed"
    }[]
    seq: number
    at: number
  } | {
    type: "usage"
    turn: number
    inputTokens: number
    outputTokens: number
    cacheReadTokens?: number
    cacheWriteTokens?: number
    contextTokens?: number
    contextWindow?: number
    costUsd?: number
    seq: number
    at: number
  } | {
    type: "turn.queued"
    commandId: string
    text: string
    seq: number
    at: number
  } | {
    type: "turn.unqueued"
    commandId: string
    reason: "canceled" | "started"
    seq: number
    at: number
  } | {
    type: "turn.steered"
    turn: number
    commandId: string
    text: string
    seq: number
    at: number
  } | {
    type: "session.configured"
    settings: {
      mode?: "ask" | "reads" | "app" | "auto"
      plan?: boolean
      model?: null | string
      effort?: null | "low" | "medium" | "high" | "max"
    }
    seq: number
    at: number
  } | {
    type: "allowlist.added"
    command: string
    seq: number
    at: number
  } | {
    type: "approval.requested"
    turn: number
    requestId: string
    kind: "read" | "edit" | "command" | "other"
    title: string
    command?: string
    paths?: string[]
    diff?: string
    outside?: boolean
    input?: {
      tool: "read"
      path: string
      offset?: number
      limit?: number
    } | {
      tool: "edit"
      path: string
      edits: {
        old: string
        new: string
      }[]
      replaceAll?: boolean
    } | {
      tool: "write"
      path: string
      content: string
    } | {
      tool: "patch"
      paths: string[]
      patch: string
    } | {
      tool: "search"
      pattern: string
      path?: string
      glob?: string
    } | {
      tool: "glob"
      pattern: string
      path?: string
    } | {
      tool: "list"
      path: string
    } | {
      tool: "command"
      command: string
      description?: string
      background?: boolean
    } | {
      tool: "todo"
      items: {
        text: string
        status: "pending" | "in_progress" | "completed"
      }[]
    } | {
      tool: "fetch"
      url: string
    } | {
      tool: "websearch"
      query: string
    } | {
      tool: "task"
      description: string
      prompt?: string
    } | {
      tool: "plan"
      plan: string
    } | {
      tool: "other"
      summary?: string
    }
    suggest?: string
    seq: number
    at: number
  } | {
    type: "approval.resolved"
    turn: number
    requestId: string
    decision: "allow" | "deny"
    by: "policy" | "person" | "stop"
    always?: boolean
    feedback?: string
    seq: number
    at: number
  } | {
    type: "turn.finished"
    turn: number
    status: "done" | "failed" | "interrupted"
    error?: string
    seq: number
    at: number
  } | {
    type: "checkpoint.created"
    turn: number
    ref: string
    seq: number
    at: number
  } | {
    type: "checkpoint.diff"
    commandId: string
    fromTurn: number
    toTurn: number
    diff: string
    truncated: boolean
    seq: number
    at: number
  } | {
    type: "checkpoint.restored"
    commandId: string
    turn: number
    seq: number
    at: number
  } | {
    type: "command.rejected"
    commandId: string
    reason: string
    seq: number
    at: number
  } | {
    type: "error"
    message: string
    retry?: {
      attempt: number
      max?: number
      delayMs?: number
    }
    seq: number
    at: number
  } | {
    type: "session.ended"
    reason: "canceled" | "failed" | "stopped"
    error?: string
    seq: number
    at: number
  } | {
    type: "file.written"
    commandId: string
    path: string
    bytes: number
    seq: number
    at: number
  } | {
    type: "changes.reverted"
    commandId: string
    path: string
    hunk: boolean
    seq: number
    at: number
  } | {
    type: "terminal.opened"
    commandId: string
    terminalId: string
    seq: number
    at: number
  } | {
    type: "terminal.closed"
    terminalId: string
    exitCode?: number
    seq: number
    at: number
  } | {
    type: "terminal.command"
    terminalId: string
    line: string
    hidden?: boolean
    seq: number
    at: number
  } | {
    type: "git.branched"
    commandId: string
    branch: string
    seq: number
    at: number
  } | {
    type: "git.committed"
    commandId: string
    sha: string
    branch: null | string
    summary: string
    seq: number
    at: number
  } | {
    type: "git.pushed"
    commandId: string
    branch: string
    remote: string
    seq: number
    at: number
  }[]
  more: boolean
}

POST/v1/me/code/sessions/:sessionId/messages

Starts a turn with your message, or queues it behind the turn running (a turn.queued event). Up to 4 images (PNG, JPEG, WebP or GIF as base64, 300 KB together). 409 when the session has ended.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

textstringrequired
1–32,000 characters. Trimmed.
imagesobject[]
Up to 4 items.
images[].mime"image/png" | "image/jpeg" | "image/webp" | "image/gif"required
images[].datastringrequired

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/messages' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/steer

Sends your message into the turn running (Codex takes it mid-turn; Claude Code's turn stops and the message runs next).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

textstringrequired
1–32,000 characters. Trimmed.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/steer' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/queue/:queued/cancel

Drops a message waiting in the queue before it starts.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
queued
The id of the command that sent a message now waiting in a Code mode session's queue, as its turn.queued event gives it.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/queue/{queued}/cancel' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/settings

Changes the session's mode (at most your mode for the assistant in its space), plan (plan mode), model and effort, from the agent's next step. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

mode"ask" | "reads" | "app" | "auto"
planboolean
modelstringor null
Up to 100 characters. Matches ^[A-Za-z0-9._:/@\[\]-]+$.
effort"low" | "medium" | "high" | "max"or null

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "ask",
    "plan": true,
    "model": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/interrupt

Stops the running turn; approvals waiting in it are declined.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/interrupt' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/approvals/:requestId

Allows or declines a step waiting for you (a command, an edit, anything outside the folder). always with an allow adds the command to the machine's list for the folder; feedback with a decline tells the agent what to do instead. Only you, from your own sign-in: not keys or the phone assistant.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
requestId
A Code mode step waiting for your approval (apr_…), as the session's approval.requested event and its pending list give it.

Request body

decision"allow" | "deny"required
alwaysboolean
feedbackstring
Up to 4,000 characters.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/approvals/{requestId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "decision": "allow"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/checkpoints/diff

Asks the machine for the patch between two turns' checkpoints; it arrives as a checkpoint.diff event with this command's id.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

fromTurnintegerrequired
0–99999. Coerced from a string.
toTurnintegerrequired
0–99999. Coerced from a string.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/checkpoints/diff' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fromTurn": 1,
    "toTurn": 1
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/checkpoints/:turn/restore

Puts the folder back as that turn's checkpoint left it (files added since are removed; ignored files stay). Only you, and not while a turn runs.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
turn
A Code mode turn's number (from 1; 0 is the folder as the session found it).

Errors

400Not a turn.
400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/checkpoints/{turn}/restore' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/stop

Ends the session: the turn interrupted, waiting approvals declined, the provider closed on the machine.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/stop' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/files/list

Asks the machine for the folder's files (git's view: ignored files left out); the answer is the stream reply-<commandId>, JSON { files, truncated }.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/files/list' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/files/read

Asks the machine for one file's text (path, inside the folder); the answer is the stream reply-<commandId>. Binary files, files over 2 MB and files likely to hold secrets come back without their text.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

pathstringrequired
1–1,000 characters.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/files/read' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/files/write

Saves your edit to a file on your machine (path, content up to 300 KB); never a file likely to hold secrets. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

pathstringrequired
1–1,000 characters.
contentstringrequired
Up to 300,000 characters.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/files/write' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "example",
    "content": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/changes/diff

Asks for the changes from checkpoint fromTurn to toTurn, or to the folder as it is now without toTurn; the patch is the stream reply-<commandId>.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

fromTurnintegerrequired
0–99999. Coerced from a string.
toTurninteger
0–99999. Coerced from a string.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/changes/diff' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fromTurn": 1
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/changes/revert

Puts path back as checkpoint fromTurn had it, or undoes one hunk of its change in the folder. Not while a turn runs.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

pathstringrequired
1–1,000 characters.
fromTurnintegerrequired
0–99999. Coerced from a string.
hunkstring
Up to 300,000 characters.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/changes/revert' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "example",
    "fromTurn": 1
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/terminals

Opens a terminal on your machine, in the session's folder, as you (cols, rows; at most 3 at once); a terminal.opened event says its id, and its output is the stream term-<terminalId>.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

colsintegerrequired
rowsintegerrequired

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/terminals' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "cols": 1,
    "rows": 1
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/terminals/:terminalId/input

Types into a terminal (data, up to 4,096 characters). Each line is recorded in the session and the audit log; one typed at a password prompt as hidden. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
terminalId
A Code mode session's terminal (trm_…), as its terminal.opened event gives it.

Request body

datastringrequired
1–4,096 characters.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/terminals/{terminalId}/input' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "data": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/terminals/:terminalId/resize

Changes a terminal's size (cols, rows).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
terminalId
A Code mode session's terminal (trm_…), as its terminal.opened event gives it.

Request body

colsintegerrequired
rowsintegerrequired

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/terminals/{terminalId}/resize' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "cols": 1,
    "rows": 1
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/terminals/:terminalId/close

Closes a terminal; a terminal.closed event follows.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
terminalId
A Code mode session's terminal (trm_…), as its terminal.opened event gives it.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/terminals/{terminalId}/close' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/status

Asks the machine for the folder's git status: its branch, upstream, ahead and behind, remote (no credentials), changes and recent commit summaries; the answer is the stream reply-<commandId>.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/status' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/diff

Asks the machine for the folder's changes against its last commit, new files too, with known kinds of keys taken out; the answer is the stream reply-<commandId>, JSON { diff, truncated }.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/diff' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/branch

Makes a new branch (name) where the folder is and switches to it; a git.branched event follows. Not while a turn runs. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

namestringrequired

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/branch' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/commit

Commits every change in the folder with message, as you (your git identity and hooks on the machine); a git.committed event says its sha. Not while a turn runs. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

messagestringrequired
1–10,000 characters. Trimmed.

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/commit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "example"
  }'

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/push

Pushes the folder's branch to its upstream, or to origin as its upstream, with your credentials on the machine; a git.pushed event follows. Only you, from your own sign-in.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Errors

400That isn't a Code mode command.
403Code mode isn't available to the phone assistant.
403Caity is off for you in this session's space.
403Your permissions for Caity in this space go up to "…".
403Code mode is for people, signed in.
404Session not found
404Job not found
409This session has ended.
409That approval isn't waiting any more.
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/push' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  commandId: null
  seq: null
} | {
  commandId: string
  seq: number
}

POST/v1/me/code/sessions/:sessionId/git/message

A commit message drafted by the assistant's fast model from diff (as git/diff answered it; the first 60 KB, keys taken out) and recent commit summaries for their style; on your allowance in the session's space. Answers { message }.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).

Request body

diffstringrequired
1–240,000 characters.
recentstring[]
Up to 20 items. Each up to 500 characters.

Errors

400There's nothing to commit.
403Code mode isn't available to the phone assistant.
403Caity is off for you in that space.
403Code mode is for people, signed in.
404Session not found
502No message came back. Try again.

curl -X POST 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/git/message' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "diff": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  message: string
}

GET/v1/me/code/sessions/:sessionId/streams/:stream

A stream's pieces after after (a command's reply or a terminal's output), in order, kept an hour; a reply read to its end is gone.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Path parameters

sessionId
A sign-in's id (cls_… for an app on a phone or the command line, ses_… for a browser), as the devices list gives it; under /v1/me/code a Code mode session (cds_…).
stream
A Code mode stream: reply-<commandId> for a request's answer, term-<terminalId> for a terminal's output.

Query parameters

afterinteger
≥ 0. Coerced from a string.

Errors

400That isn't a stream.
403Code mode is for people, signed in.
404Session not found

curl 'https://api.cactive.com.au/v1/me/code/sessions/{sessionId}/streams/{stream}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  chunks: {
    seq: number
    data: string
    done?: boolean
  }[]
  more: boolean
}