Skip to main content
POST
/
api
/
v1
/
terminal
/
code
Start a code session
curl --request POST \
  --url http://localhost:3001/api/v1/terminal/code \
  --header 'Content-Type: application/json' \
  --cookie nut-session= \
  --data '
{
  "taskId": "<string>",
  "model": "claude",
  "contextType": "change-task",
  "autonomous": false,
  "interactive": true,
  "customInstructions": "<string>",
  "newWorktree": false,
  "worktreeBranch": "<string>",
  "worktreeSuffix": "<string>"
}
'
{
  "sessionId": "<string>",
  "taskId": "<string>",
  "command": "<string>",
  "scriptPath": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
nut-session
string
cookie
required

Session cookie authentication

Body

application/json
​
taskId
string
required

Task ID to implement

​
model
enum<string>
default:claude

AI agent to use

Available options:
claude,
gemini,
codex,
droid,
kiro
​
contextType
enum<string>
default:change-task

Context type for the session

Available options:
change-task,
prepare-task,
skill,
general
​
autonomous
boolean
default:false

Enable autonomous / skip-permissions mode

​
interactive
boolean
default:true

When true (default) the agent stays open after completing the task. When false the agent exits on completion and the terminal session closes.

​
customInstructions
string

Custom instructions for the agent

​
newWorktree
boolean
default:false

Create a new git worktree for this session

​
worktreeBranch
string

Override worktree branch name

​
worktreeSuffix
string

Append a suffix to the generated worktree branch name

Response

Code session started

​
sessionId
string
​
taskId
string
​
command
string

The pipeline command sent to the terminal

​
scriptPath
string

Path to the temp file containing the pipeline script

​
createdAt
string<date-time>