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

# List tasks

> Retrieve a list of tasks with optional filtering, search, and pagination.
By default returns lightweight summaries (content truncated, comments omitted).
Use `full=true` to include full content, planSteps, and comments.
When `q` is provided, results include a `snippet` field with context around matches and a relevance `score`.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/v1/tasks
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/tasks:
    get:
      tags:
        - Tasks
      summary: List tasks
      description: >
        Retrieve a list of tasks with optional filtering, search, and
        pagination.

        By default returns lightweight summaries (content truncated, comments
        omitted).

        Use `full=true` to include full content, planSteps, and comments.

        When `q` is provided, results include a `snippet` field with context
        around matches and a relevance `score`.
      operationId: listTasks
      parameters:
        - name: status
          in: query
          description: Filter by task status
          schema:
            $ref: '#/components/schemas/TaskStatus'
        - name: author
          in: query
          description: Filter by author
          schema:
            type: string
        - name: priority
          in: query
          description: Filter by priority level
          schema:
            type: string
            enum:
              - low
              - medium
              - high
              - critical
        - name: tags
          in: query
          description: Filter by tags (comma-separated)
          schema:
            type: string
        - name: q
          in: query
          description: >-
            Fuzzy search across title, content, ID, author name, and tags.
            Results are ranked by relevance and include snippet/score fields.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results per page (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Number of results to skip for pagination (default 0)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: full
          in: query
          description: >-
            Set to "true" to include full content, planSteps, and comments
            instead of summaries
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      query:
                        type: string
                        description: >-
                          Echo of the search query (only present when q is
                          provided)
                      totalCount:
                        type: integer
                        description: Total number of matching tasks (before pagination)
                      count:
                        type: integer
                        description: Number of tasks in this response page
                      limit:
                        type: integer
                        description: Page size (only present when limit is specified)
                      offset:
                        type: integer
                        description: Number of results skipped
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Task'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TaskStatus:
      type: string
      enum:
        - draft
        - backlog
        - ready
        - queued
        - active
        - blocked
        - review
        - revision
        - done
        - canceled
        - duplicate
      description: Task status
    SuccessResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
    Task:
      type: object
      required:
        - id
        - title
        - status
      properties:
        id:
          type: string
          description: Unique task ID
        title:
          type: string
          description: Task title/summary
        intent:
          type: string
          description: Intent (deprecated, use 'title' instead)
          deprecated: true
        content:
          type: string
          description: Task content/body (markdown)
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
        readiness:
          type: integer
          minimum: 0
          maximum: 100
          description: Readiness score (0-100)
        tags:
          type: array
          items:
            type: string
        author:
          $ref: '#/components/schemas/Author'
        reviewers:
          type: array
          items:
            type: string
          description: List of reviewers (names or emails)
        planSteps:
          type: array
          items:
            $ref: '#/components/schemas/PlanStep'
          description: Implementation plan steps
        comments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              author:
                type: string
              content:
                type: string
              createdAt:
                type: string
                format: date-time
        changes:
          type: array
          items:
            $ref: '#/components/schemas/FileChange'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Author:
      type: object
      properties:
        type:
          type: string
          enum:
            - user
            - agent
          description: Author type
        id:
          type: string
          description: Author identifier
        name:
          type: string
          description: Display name
    PlanStep:
      type: object
      required:
        - id
        - description
        - status
      properties:
        id:
          type: string
          description: Step ID (e.g. step-01)
        description:
          type: string
          description: Step description
        status:
          $ref: '#/components/schemas/StepStatus'
        command:
          type: string
          description: Command to execute for this step
        expectedOutcome:
          type: string
          description: Expected outcome of this step
        output:
          type: string
          description: Step output
        error:
          type: string
          description: Error message if step failed
        executedAt:
          type: string
          format: date-time
          description: When the step was executed
    FileChange:
      type: object
      properties:
        path:
          type: string
          description: File path
        type:
          type: string
          enum:
            - create
            - modify
            - delete
            - rename
        content:
          type: string
          description: File content (for create/modify)
        oldPath:
          type: string
          description: Original path (for rename)
    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
    StepStatus:
      type: string
      enum:
        - pending
        - active
        - done
        - failed
        - skipped
      description: Plan step status
  responses:
    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

````