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

# List versions

> Every published version, newest first (the latest 500): when, by whom and with what note.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/agents/{agent_id}/versions
openapi: 3.1.0
info:
  title: GuidingHand API
  version: 1.0.0
  description: >-
    Create sessions (an invite link with a code for the person at the computer),
    run tasks on their computer with one of your agents, follow them, answer
    their questions and approvals, and fetch history and recordings. Test your
    agents with evals: test cases on fresh machines, run in test sets, scored by
    a check script or a rubric. Agents are versioned (save a draft, publish it),
    have tools (their own file system, and your HTTP endpoints), and every
    change is in the org’s audit log.
servers:
  - url: https://guidinghand.ai
    description: Production
  - url: https://dev.guidinghand.ai
    description: Development (Stripe test mode)
security:
  - bearerAuth: []
tags:
  - name: Agents
  - name: Agent files
  - name: Agent tools
  - name: Sessions
  - name: Tasks
  - name: Webhooks
  - name: Audit log
  - name: Test cases
  - name: Test sets
  - name: Test runs
  - name: Start states
  - name: Runners
paths:
  /v1/agents/{agent_id}/versions:
    parameters:
      - name: agent_id
        in: path
        required: true
        description: The agent’s id, e.g. `billing` or `default`.
        schema:
          type: string
    get:
      tags:
        - Agents
      summary: List versions
      description: >-
        Every published version, newest first (the latest 500): when, by whom
        and with what note.
      operationId: listAgentVersions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - has_more
                  - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentVersion'
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: Pass as `cursor` to get the next page.
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
components:
  schemas:
    AgentVersion:
      type: object
      properties:
        object:
          const: agent_version
        agent_id:
          type: string
          example: billing
        version:
          type: integer
          minimum: 1
          example: 3
        note:
          type: string
          description: What changed, as given when it was published, or empty.
          example: Order lookup
        published_at:
          type:
            - string
            - 'null'
          format: date-time
        published_by:
          $ref: '#/components/schemas/Actor'
          description: >-
            Who published it. Null for an agent’s first version when it was made
            before versions were kept.
    Actor:
      oneOf:
        - title: Person
          type: object
          description: A person in the org (in the console).
          properties:
            type:
              const: user
            email:
              type:
                - string
                - 'null'
              example: jane@acme.com
        - title: API key
          type: object
          description: One of the org’s API keys.
          properties:
            type:
              const: api_key
            key_id:
              type: string
            name:
              type:
                - string
                - 'null'
              example: Zendesk
            prefix:
              type:
                - string
                - 'null'
              description: The key’s first characters.
              example: gh_live_AbC1
        - type: 'null'
      description: >-
        Who did it: a person (in the console) or an API key. Null when nobody
        was recorded: it was made with a session token, by GuidingHand itself,
        or before this was kept.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication
                - payment_required
                - permission
                - not_found
                - conflict
                - rate_limit
                - server_error
            message:
              type: string
            code:
              type: string
              description: >-
                Why it was refused, when there’s more to say than the status.
                Starting a task: `insufficient_balance`,
                `auto_topup_limit_reached` or `card_needs_attention` (402: the
                balance can’t cover a minute; add funds, raise the auto top-up
                limit, or update the card), `concurrency_limit` (429),
                `model_unavailable` (503: the agent’s `model` can’t run on this
                server; choose another). On `/respond`: `already_answered`
                (someone answered or decided first: see `answered_by`) or
                `not_pending` (that question or approval isn’t open any more).
                The GuidingHand app hears two more, which the API never returns:
                `customer_answers_off` and `customer_approvals_off` (the agent
                keeps its questions or approvals for your team). Deleting a
                start state that test cases use: `in_use` (409, with
                `test_case_ids`).
            answered_by:
              type: string
              enum:
                - customer
                - operator
                - timeout
              description: >-
                With `already_answered`: who answered or decided first
                (`customer`: the person at the computer; `timeout`: nobody
                decided an approval within the agent’s
                `approval_timeout_minutes`, so it was denied).
            test_case_ids:
              type: array
              items:
                type: string
              description: 'With `in_use`: the test cases that use the start state.'
  responses:
    E401:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E404:
      description: Not found in this org.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An org API key (`gh_live_…`) from Settings → API keys in the console.

````