> ## 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.

# AI chat

> Send a message to the AI assistant. The server uses Claude Sonnet 4.5 (default)
via the Vercel AI SDK. The system prompt is built from the shared Coconut assistant
prompt plus, when present on disk, `.nut/context/role.md` and `.nut/context/memory.md`
(appended as instance context). Tools (tasks, knowledge, events, role context,
agents context, team context, memory context) are handled automatically server-side with
multi-step tool execution. The response is a plain-text stream of assistant content.




## OpenAPI

````yaml /api-reference/openapi.yaml post /api/v1/ai
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/ai:
    post:
      tags:
        - AI
      summary: AI chat
      description: >
        Send a message to the AI assistant. The server uses Claude Sonnet 4.5
        (default)

        via the Vercel AI SDK. The system prompt is built from the shared
        Coconut assistant

        prompt plus, when present on disk, `.nut/context/role.md` and
        `.nut/context/memory.md`

        (appended as instance context). Tools (tasks, knowledge, events, role
        context,

        agents context, team context, memory context) are handled automatically
        server-side with

        multi-step tool execution. The response is a plain-text stream of
        assistant content.
      operationId: aiChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: The user message to send
                history:
                  type: array
                  description: Previous conversation messages
                  items:
                    $ref: '#/components/schemas/ChatMessage'
                skillPersona:
                  type: string
                  description: |
                    Skill persona block to append to the system prompt.
                    Overrides general guidance when provided.
                agentPersona:
                  type: string
                  deprecated: true
                  description: |
                    Deprecated — use `skillPersona` instead.
                    Agent persona block to append to the system prompt.
                systemPrompt:
                  type: string
                  description: |
                    Custom system prompt. When omitted the server uses the
                    default project-aware system prompt.
                attachedContextFiles:
                  type: array
                  description: |
                    Additional context files to include in the conversation.
                    Each entry is injected as a user/assistant message pair
                    before the final user message.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Display name for the context file
                      type:
                        type: string
                        description: Type of context (e.g. "context", "task")
                      content:
                        type: string
                        description: The context content
      responses:
        '200':
          description: |
            Streamed plain-text response. The body is a UTF-8 text stream
            containing only the assistant's generated content (tool calls
            and results are processed server-side and not exposed).
          content:
            text/plain:
              schema:
                type: string
                description: Plain-text stream of assistant content
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - tool
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
          description: Message content
        name:
          type: string
          description: Name (for tool messages)
        toolCalls:
          type: array
          items:
            type: object
          description: Tool calls (for assistant messages)
        toolCallId:
          type: string
          description: Tool call ID (for tool messages)
    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
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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

````