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

> Every org has a `default` agent, even before it is customized.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/agents
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.
servers:
  - url: https://guidinghand.ai
    description: Production
  - url: https://dev.guidinghand.ai
    description: Development (Stripe test mode)
security:
  - bearerAuth: []
tags:
  - name: Agents
  - name: Sessions
  - name: Tasks
  - name: Webhooks
paths:
  /v1/agents:
    get:
      tags:
        - Agents
      summary: List agents
      description: Every org has a `default` agent, even before it is customized.
      operationId: listAgents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - has_more
                  - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: Pass as `cursor` to get the next page.
        '401':
          $ref: '#/components/responses/E401'
components:
  schemas:
    Agent:
      type: object
      properties:
        object:
          const: agent
        agent_id:
          type: string
          example: billing
        name:
          type: string
          example: Billing help
        instructions:
          type: string
          description: Added under GuidingHand’s own rules, which always win.
        effort:
          $ref: '#/components/schemas/Effort'
        greeting:
          type: string
          description: Shown to the person on the invite page.
        display_name:
          type: string
          description: >-
            What the GuidingHand app calls the agent on the person’s screen
            while it works (“Acme Support is typing”). Empty means
            “GuidingHand”.
          example: Acme Support
        narration:
          type: boolean
          description: >-
            The app shows the agent’s thoughts and steps on the person’s screen
            as it works, and its summary when it finishes. These are the agent’s
            own words, so they can repeat what your team answered. Off: no
            thoughts, steps or summary; they see the banner with the Stop button
            (and the agent’s questions and approval requests, if
            `customer_answers` and `customer_approvals` are on).
        customer_answers:
          type: boolean
          description: >-
            The person at the computer can answer the agent’s questions in the
            GuidingHand app (your team still can too; the first answer is used).
            Off: only your team answers, and the question isn’t shown on the
            person’s screen.
        customer_approvals:
          type: boolean
          description: >-
            The person at the computer can approve or deny the agent’s approval
            requests in the GuidingHand app (your team still can too; the first
            decision is used). Off: only your team decides, and the request
            isn’t shown on the person’s screen.
        is_default:
          type: boolean
        invite_url_template:
          type: string
          example: https://guidinghand.ai/acme/billing/{code}
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    Effort:
      type:
        - string
        - 'null'
      enum:
        - low
        - medium
        - high
        - null
      description: How much the model thinks per step. Null for GuidingHand’s default.
    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 an answer or decision was refused (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).
            answered_by:
              type: string
              enum:
                - customer
                - operator
              description: >-
                With `already_answered`: who answered or decided first
                (`customer`: the person at the computer).
  responses:
    E401:
      description: Missing or invalid API key.
      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.

````