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

# List agents

> Returns the agents a user can start: Circuit's agents and popular community agents. With a permit, it also returns the user's own agents and marks them `yours`. Works without a permit, so you can show agents before the user links. Pass an agent's `id` to start a session.



## OpenAPI

````yaml /partner-openapi.gen.json get /partner/v0.1/agents
openapi: 3.1.0
info:
  title: Circuit partner API
  version: '0.1'
servers:
  - url: https://api.circuit.org
security: []
paths:
  /partner/v0.1/agents:
    get:
      summary: List agents
      description: >-
        Returns the agents a user can start: Circuit's agents and popular
        community agents. With a permit, it also returns the user's own agents
        and marks them `yours`. Works without a permit, so you can show agents
        before the user links. Pass an agent's `id` to start a session.
      operationId: listAgents
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: The agents the user can start.
                type: object
                properties:
                  agents:
                    description: >-
                      Circuit's agents and popular community agents, plus the
                      user's own when you send a permit. The agents most people
                      started in the last 30 days come first, and Circuit's
                      agents come first among equals.
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                required:
                  - agents
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerFailure'
      security:
        - {}
        - permit: []
components:
  schemas:
    Agent:
      description: >-
        An agent the user can start: a published program that trades on its own
        schedule.
      type: object
      properties:
        id:
          description: The agent's id, starting with `agt_`. Pass it to start a session.
          type: string
        name:
          description: The agent's name.
          type: string
        description:
          description: One line on what the agent does. Null when its creator wrote none.
          type:
            - string
            - 'null'
        official:
          description: True when Circuit made the agent.
          type: boolean
        yours:
          description: True when the user made the agent. Always false without a permit.
          type: boolean
        return_percent:
          description: >-
            How much its sessions have returned since they started, as a decimal
            percent. Null when unknown.
          type:
            - string
            - 'null'
        paper:
          description: >-
            True when the agent can run on paper money, false when it needs real
            money. Null for a few seconds after its creator publishes a new
            version, while Circuit checks it.
          type:
            - boolean
            - 'null'
        people:
          description: How many people started this agent in the last 30 days.
          type: integer
          format: int32
      required:
        - id
        - name
        - official
        - yours
        - people
    PartnerFailure:
      description: >-
        A failed call. Handle it by HTTP status and `code`, and show `error` to
        the user.
      type: object
      properties:
        error:
          description: A message you can show the user.
          type: string
        code:
          description: >-
            A stable code such as `BAD_REQUEST`, `NOT_FOUND`, `CONFLICT` or
            `UNAUTHORIZED`. New codes can appear.
          type: string
      required:
        - error
        - code
  securitySchemes:
    permit:
      description: The permit the user approved for your app.
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.