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

# List statuses

> Returns all custom task statuses for the project, ordered by their display order.

Use the returned `id` values as `statusId` when creating or filtering tasks.

Requires the `task:read` scope.



## OpenAPI

````yaml /api-reference/api.json get /{projectSlug}/statuses
openapi: 3.1.0
info:
  title: Elean Public API
  description: >-
    The Elean Public API allows external clients — scripts, AI agents, and
    integrations — to read and write tasks programmatically.


    > **Early Access:** This API is currently in beta. Endpoints,
    request/response shapes, and scopes may change before the stable release. We
    will communicate breaking changes in advance.
  version: 0.0.1
  contact:
    name: Elean Support
    url: https://elean.app
servers:
  - url: https://api.elean.app/v1/public
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Statuses
    description: List the custom task statuses configured for a project.
  - name: Labels
    description: List labels available in a project.
  - name: Members
    description: List members of a project.
  - name: Tasks
    description: Read and write tasks within a project.
  - name: Comments
    description: Read and write comments on tasks.
paths:
  /{projectSlug}/statuses:
    get:
      tags:
        - Statuses
      summary: List statuses
      description: >-
        Returns all custom task statuses for the project, ordered by their
        display order.


        Use the returned `id` values as `statusId` when creating or filtering
        tasks.


        Requires the `task:read` scope.
      operationId: listStatuses
      parameters:
        - name: projectSlug
          in: path
          required: true
          description: The slug of the project.
          schema:
            type: string
            example: my-project
      responses:
        '200':
          description: A list of custom statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskStatus'
              example:
                - id: 018e1b2c-aaaa-0000-0000-000000000001
                  name: Backlog
                  color: '#6b7280'
                  category: todo
                  order: 1
                - id: 018e1b2c-aaaa-0000-0000-000000000002
                  name: In Review
                  color: '#f59e0b'
                  category: in_progress
                  order: 2
                - id: 018e1b2c-aaaa-0000-0000-000000000003
                  name: Done
                  color: '#22c55e'
                  category: done
                  order: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    TaskStatus:
      type: object
      description: A custom task status defined for a project.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Unique identifier of the status. Use this as `statusId` when
            creating or filtering tasks.
          example: 018e1b2c-aaaa-0000-0000-000000000002
        name:
          type: string
          description: Display name of the status.
          example: In Review
        color:
          type:
            - string
            - 'null'
          description: Hex color code for the status, or `null` if not set.
          example: '#f59e0b'
        category:
          type: string
          enum:
            - todo
            - in_progress
            - done
          description: >-
            Semantic category of the status. Used for broad filtering via the
            `status` query parameter.
          example: in_progress
        order:
          type: integer
          description: Display order within the project.
          example: 2
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid API key
  responses:
    Unauthorized:
      description: The API key is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 401
            message: Invalid API key
    Forbidden:
      description: >-
        The API key does not have the required scope, or the project is outside
        the key's allowed scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 403
            message: 'Missing required scope: task:create'
    NotFound:
      description: The project or task was not found within the key's workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 404
            message: Task not found
    TooManyRequests:
      description: >-
        The rate limit for this API key has been exceeded. Retry after the
        indicated delay.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 429
            message: Too many requests
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: el_<token>
      description: >-
        API key created in **Workspace Settings → API Keys**. Pass it in the
        `Authorization` header as a Bearer token, or in the `X-API-Key` header.


        Format: `el_` followed by 40 hex characters.

````