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

> List an agent's versions, newest first. Filter by status, tag, label,
or version number; set ``exclude_revisions`` to see only base versions.



## OpenAPI

````yaml https://api-v3.aui.io/apollo-api/openapi.json get /management/v1/agents/{agentId}/versions
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/agents/{agentId}/versions:
    get:
      tags:
        - Agent Versions
      summary: List versions
      description: |-
        List an agent's versions, newest first. Filter by status, tag, label,
        or version number; set ``exclude_revisions`` to see only base versions.
      operationId: list_versions
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
            title: Agentid
        - name: filters
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/AgentVersionListFilters'
        - 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_AgentVersion_'
        '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:
    AgentVersionListFilters:
      properties:
        status:
          anyOf:
            - items:
                type: string
                enum:
                  - draft
                  - published
                  - archived
              type: array
            - type: 'null'
          title: Status
        tag:
          anyOf:
            - type: string
            - type: 'null'
          title: Tag
          description: Filter by tag (partial match)
        version_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Version Number
          description: Filter by version number (exact match)
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
          description: Filter by label (partial match)
        exclude_revisions:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Exclude Revisions
          description: If true, only return base versions (revision 0)
      type: object
      title: AgentVersionListFilters
      description: |-
        Query filters for listing an agent's versions (sort/pagination come from
        the shared page-query dependency, not from here).
    Page_AgentVersion_:
      properties:
        results:
          items:
            $ref: '#/components/schemas/AgentVersion'
          type: array
          title: Results
        meta:
          $ref: '#/components/schemas/PageMeta'
        links:
          $ref: '#/components/schemas/PageLinks'
      type: object
      required:
        - results
        - meta
        - links
      title: Page[AgentVersion]
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
        - error
      title: ErrorResponse
      description: The single envelope every Apollo error response conforms to.
    AgentVersion:
      properties:
        id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          title: Id
          description: Version id
        agent_id:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          title: Agent Id
          description: Owning agent id
        version_number:
          type: integer
          title: Version Number
        version_revision_number:
          type: integer
          title: Version Revision Number
        version_tag:
          type: string
          title: Version Tag
          description: Canonical tag, e.g. 'v3.2'
        status:
          type: string
          enum:
            - draft
            - published
            - archived
          title: Status
        parent_version_id:
          anyOf:
            - type: string
              pattern: ^[0-9a-fA-F]{24}$
            - type: 'null'
          title: Parent Version Id
          description: 'Lineage: cloned from'
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        tags:
          items:
            type: string
          type: array
          title: Tags
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        stats:
          anyOf:
            - $ref: '#/components/schemas/VersionStats'
            - type: 'null'
        created_at:
          type: string
          format: date-time
          title: Created At
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
      type: object
      required:
        - id
        - agent_id
        - version_number
        - version_revision_number
        - version_tag
        - status
        - created_at
      title: AgentVersion
      description: An agent version — an immutable-once-published config snapshot.
    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.
    VersionStats:
      properties:
        workflows:
          type: integer
          title: Workflows
          default: 0
        policies:
          type: integer
          title: Policies
          default: 0
        agent_placeholders:
          type: integer
          title: Agent Placeholders
          default: 0
        scope_entities:
          type: integer
          title: Scope Entities
          default: 0
        integrations:
          type: integer
          title: Integrations
          default: 0
        card_templates:
          type: integer
          title: Card Templates
          default: 0
        parameters:
          type: integer
          title: Parameters
          default: 0
        knowledge_bases:
          type: integer
          title: Knowledge Bases
          default: 0
        agent_properties:
          type: integer
          title: Agent Properties
          default: 0
      type: object
      title: VersionStats
      description: Counts of the entities configured in a version.
    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.

````