> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coconut.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a code session

> Create a terminal session for a task, build the pipeline command for the
selected AI agent, and send it to the terminal. Returns the session ID
so callers can connect via the WebSocket endpoint to monitor progress.




## OpenAPI

````yaml /api-reference/openapi.yaml post /api/v1/terminal/code
openapi: 3.1.1
info:
  title: Coconut API
  description: |
    Comprehensive API for the Coconut development platform.

    Coconut is a development environment that provides AI-assisted coding,
    task management, skill orchestration, and integrated terminal sessions.
  version: 1.0.72
  contact:
    name: Coconut Team
  license:
    name: MIT
servers:
  - url: http://localhost:3001
    description: Development server
  - url: '{baseUrl}'
    description: Production server
    variables:
      baseUrl:
        default: http://localhost:3001
        description: Base URL for the API
security:
  - sessionCookie: []
  - bearerAuth: []
  - apiKey: []
tags:
  - name: Tasks
    description: Task management
  - name: Skills
    description: AI skill configuration and management (Agent Skills spec)
  - name: Resources
    description: File and media resource management
  - name: Knowledge
    description: Knowledge document management
  - name: Terminal
    description: Terminal session management
  - name: AI
    description: AI chat and completion endpoints
  - name: Chats
    description: Chat history management
  - name: Configuration
    description: Project and global configuration
  - name: MCP
    description: Model Context Protocol server management
  - name: Context
    description: Context documents for role, agents, team, and memory
  - name: Identity
    description: Identity and agent card management
  - name: User
    description: User information and settings
  - name: Jobs
    description: Scheduled job management
  - name: Git
    description: Git repository management
  - name: Slack
    description: Slack integration and notification management
  - name: Mail
    description: Email management and Resend webhook integration
  - name: Version
    description: API version information
paths:
  /api/v1/terminal/code:
    post:
      tags:
        - Terminal
      summary: Start a code session
      description: |
        Create a terminal session for a task, build the pipeline command for the
        selected AI agent, and send it to the terminal. Returns the session ID
        so callers can connect via the WebSocket endpoint to monitor progress.
      operationId: startCodeSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
              properties:
                taskId:
                  type: string
                  description: Task ID to implement
                model:
                  type: string
                  enum:
                    - claude
                    - gemini
                    - codex
                    - droid
                    - kiro
                  default: claude
                  description: AI agent to use
                contextType:
                  type: string
                  enum:
                    - change-task
                    - prepare-task
                    - skill
                    - general
                  default: change-task
                  description: Context type for the session
                autonomous:
                  type: boolean
                  default: false
                  description: Enable autonomous / skip-permissions mode
                interactive:
                  type: boolean
                  default: true
                  description: >
                    When true (default) the agent stays open after completing
                    the task. When false the agent exits on completion and the
                    terminal session closes.
                customInstructions:
                  type: string
                  description: Custom instructions for the agent
                newWorktree:
                  type: boolean
                  default: false
                  description: Create a new git worktree for this session
                worktreeBranch:
                  type: string
                  description: Override worktree branch name
                worktreeSuffix:
                  type: string
                  description: Append a suffix to the generated worktree branch name
      responses:
        '200':
          description: Code session started
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                  taskId:
                    type: string
                  command:
                    type: string
                    description: The pipeline command sent to the terminal
                  scriptPath:
                    type: string
                    description: Path to the temp file containing the pipeline script
                  createdAt:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: nut-session
      description: Session cookie authentication
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication

````