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

# List threads

> List your organization's conversation threads, newest first. Repeatable
filters (``tool``, ``rule``, ``param``, ``created``) OR within a field and
AND across fields.



## OpenAPI

````yaml https://api-v3.aui.io/apollo-api/openapi.json get /management/v1/threads
openapi: 3.1.0
info:
  title: Apollo API
  description: >-
    Build conversational experiences on your agents and manage them
    programmatically.


    The API has two surfaces:


    - **Messaging** (`/messaging/v1`) — send end-user messages to your agent and
    read conversations back. Replies are available as a single JSON response, a
    Server-Sent Events token stream (`POST /messaging/v1/messages/stream`), or a
    bidirectional WebSocket session (see the companion AsyncAPI document at
    `/asyncapi.yaml`).

    - **Management** (`/management/v1`) — manage agents, their versions,
    projects, and conversation threads.


    **Authentication** — exchange your publishable key for a short-lived access
    token at `POST /management/v1/auth/token`, then send it as `Authorization:
    Bearer <access_token>`. Management endpoints also accept an organization API
    key via the `x-organization-api-key` header.


    **Errors** — every failure returns `{"error": {"code", "message",
    "request_id", "details"}}`. Branch on the stable `code`; include
    `request_id` when contacting support.
  version: 0.1.0
servers:
  - url: https://api-v3.aui.io/apollo-api
security: []
tags:
  - name: Auth
    description: >-
      Exchange a credential for a short-lived access token — start here. Send
      the token as `Authorization: Bearer <access_token>` on every other
      endpoint (management endpoints also accept an organization API key via the
      `x-organization-api-key` header).
  - name: Messaging
    description: >-
      Talk to your agent: send end-user messages (JSON reply or SSE token
      stream), rerun an interaction, and read a conversation's messages and
      reasoning traces. Threads are created automatically on the first message —
      pass the returned `thread_id` to continue a conversation.
  - name: Channels
    description: >-
      Reach end users on WhatsApp and SMS: send the opening message and bind the
      recipient's phone number to a conversation thread; replies flow through
      the same thread.
  - name: Threads
    description: >-
      Conversation threads: list and filter them, fetch one with its transcript
      and traces, and update its title.
  - name: Agents
    description: Create and manage the agents in a project.
  - name: Agent Versions
    description: >-
      An agent's configuration versions: list and inspect them, and publish a
      new live version.
  - name: Projects
    description: Projects group your agents within an organization.
  - name: Health
    description: Service liveness.
paths:
  /management/v1/threads:
    get:
      tags:
        - Threads
      summary: List threads
      description: >-
        List your organization's conversation threads, newest first. Repeatable

        filters (``tool``, ``rule``, ``param``, ``created``) OR within a field
        and

        AND across fields.
      operationId: list_threads
      parameters:
        - name: filters
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ThreadListFilters'
        - name: page[size]
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 50
            title: Page[Size]
        - name: page[after]
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Page[After]
        - name: page[before]
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Page[Before]
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            default: created_at
            title: Sort By
        - name: sort_order
          in: query
          required: false
          schema:
            enum:
              - asc
              - desc
            type: string
            default: desc
            title: Sort Order
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_ThreadListItem_'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Content
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
      security:
        - bearerAuth: []
        - organizationApiKey: []
components:
  schemas:
    ThreadListFilters:
      properties:
        project_id:
          anyOf:
            - type: string
              pattern: ^[0-9a-fA-F]{24}$
            - type: 'null'
          title: Project Id
          description: Filter by project (account) id
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: Filter by end-user id
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: Filter by caller-supplied external id
        created:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Created
          description: RFC3339 timestamp(s); two values = a [start, end] range
        tool:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool
          description: Filter by activated tool code(s)
        rule:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Rule
          description: Rule 'code', or 'code:fired|blocked|passed'
        param:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Param
          description: '''key:value'', ''key:*'', or ''key'' with >,<,>=,<='
        agent_id:
          anyOf:
            - items:
                type: string
                pattern: ^[0-9a-fA-F]{24}$
              type: array
            - type: 'null'
          title: Agent Id
          description: Filter by agent id(s)
      type: object
      title: ThreadListFilters
      description: >-
        Query filters for listing threads. Repeatable filters (``tool``,

        ``rule``, ``param``, ``created``) OR within a field and AND across
        fields.
    Page_ThreadListItem_:
      properties:
        results:
          items:
            $ref: '#/components/schemas/ThreadListItem'
          type: array
          title: Results
        meta:
          $ref: '#/components/schemas/PageMeta'
        links:
          $ref: '#/components/schemas/PageLinks'
      type: object
      required:
        - results
        - meta
        - links
      title: Page[ThreadListItem]
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
        - error
      title: ErrorResponse
      description: The single envelope every Apollo error response conforms to.
    ThreadListItem:
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          title: Id
          description: Thread id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Thread title
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: Creation timestamp (ISO-8601)
      type: object
      required:
        - id
      title: ThreadListItem
    PageMeta:
      properties:
        has_more:
          type: boolean
          title: Has More
        after_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: After Cursor
        before_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Before Cursor
      type: object
      required:
        - has_more
      title: PageMeta
    PageLinks:
      properties:
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
        prev:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev
      type: object
      title: PageLinks
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable, namespaced machine code clients branch on (e.g. "not_found"
            or "agents.not_found"). THE branch point -- open/extensible,
            append-only.
        message:
          type: string
          title: Message
          description: >-
            Human-readable explanation. NOT part of the contract; may change
            anytime. Clients must never parse or branch on this.
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Trace id for support correlation.
        details:
          anyOf:
            - items:
                $ref: '#/components/schemas/ErrorDetail'
              type: array
            - type: 'null'
          title: Details
          description: Optional structured sub-errors (e.g. per-field validation failures).
      type: object
      required:
        - code
        - message
      title: ErrorBody
      description: |-
        The error body an end user receives when interacting with Apollo.

        ``code`` is the stable, machine-readable branch point clients switch on.
        ``message`` is human-readable and explicitly NOT part of the contract --
        it may change at any time and must never be parsed.
    ErrorDetail:
      properties:
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ErrorDetail
      description: A single structured sub-error (e.g. one field's validation failure).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token from `POST /management/v1/auth/token` (publishable-key
        exchange) or a login session. Publishable-key tokens are agent-scoped
        and serve the messaging surface; login tokens also serve management.
    organizationApiKey:
      type: apiKey
      in: header
      name: x-organization-api-key
      description: >-
        Organization API key — alternative to a Bearer token on the management
        surface.

````