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

# List agents

> Lists published agents the API key creator can currently read.



## OpenAPI

````yaml /openapi/public-api.yaml get /v1/public/agents
openapi: 3.1.0
info:
  title: Erstan Public Agent API
  version: 1.2.0
  description: >-
    Start published Erstan agents from external systems and poll for results.
    API keys carry scopes (`agents:list`, `agents:read`, `agents:write`,
    `agents:run`, `runs:read`, `tasks:execute`, `documents:read`,
    `documents:write`, `files:read`, `files:write`). Agent access follows the
    key creator's current workspace and team permissions. Project and team
    allowlists (`allowedProjectIds`, `allowedTeamIds`) further restrict task and
    document and file access. Agent draft authoring and task/document/file tools
    are exposed through the MCP server at `/v1/mcp` rather than REST routes.
servers:
  - url: https://api.erstan.com
    description: Public endpoint
security:
  - PublicApiKey: []
tags:
  - name: Agents
    description: >-
      Discover and run published agents available to the key creator under their
      current permissions.
  - name: Runs
    description: Read run status and results.
  - name: MCP
    description: >-
      Model Context Protocol server for external clients. Agent Builder tools
      use `agents:read`, `agents:write`, or both, plus the key creator's live
      Erstan permissions. Task and content tools also apply project/team
      allowlists.
paths:
  /v1/public/agents:
    get:
      tags:
        - Agents
      summary: List agents
      description: Lists published agents the API key creator can currently read.
      operationId: listPublicAgents
      responses:
        '200':
          description: Published agents visible to the API key.
          content:
            application/json:
              schema:
                type: object
                required:
                  - agents
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublicAgent'
              examples:
                singleLaneAgent:
                  value:
                    agents:
                      - id: clx_agent_123
                        name: OCR Quote Intake
                        description: Extract quote data from emails and attachments.
                        behaviorType: pipeline
                        lanes:
                          - id: start_ocr_quote_intake
                            name: OCR Quote Intake
                            mode: structured
                            inputSchema:
                              type: object
                              additionalProperties: true
                              required:
                                - sourceRecordType
                                - sourceRecordId
                              properties:
                                sourceRecordType:
                                  type: string
                                sourceRecordId:
                                  type: string
                                emailBody:
                                  type: string
                            attachments:
                              supported: true
                              required: false
                              fields: []
                              acceptedTypes: []
                              maxRequestBytes: 26214400
                        defaultLaneId: start_ocr_quote_intake
                        updatedAt: '2026-05-26T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - PublicApiKey: []
components:
  schemas:
    PublicAgent:
      type: object
      required:
        - id
        - name
        - behaviorType
        - lanes
        - updatedAt
      properties:
        id:
          type: string
          description: Agent workflow ID.
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        behaviorType:
          type:
            - string
            - 'null'
        lanes:
          type: array
          items:
            $ref: '#/components/schemas/PublicAgentLane'
        defaultLaneId:
          type: string
          description: Present only when the agent has exactly one public lane.
        updatedAt:
          type: string
          format: date-time
    PublicAgentLane:
      type: object
      required:
        - id
        - name
        - mode
        - inputSchema
        - attachments
      properties:
        id:
          type: string
          description: >-
            Lane ID. This is the same ID shown in the Erstan frontend for the
            lane.
        name:
          type: string
        mode:
          $ref: '#/components/schemas/LaneMode'
        inputSchema:
          type: object
          additionalProperties: true
          description: JSON Schema for the `input` object accepted by this lane.
        attachments:
          $ref: '#/components/schemas/AttachmentPolicy'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            requestId:
              type: string
    LaneMode:
      type: string
      enum:
        - structured
        - chat
    AttachmentPolicy:
      type: object
      required:
        - supported
        - required
        - fields
        - acceptedTypes
        - maxRequestBytes
      properties:
        supported:
          type: boolean
        required:
          type: boolean
        fields:
          type: array
          items:
            type: string
        acceptedTypes:
          type: array
          items:
            type: string
        maxRequestBytes:
          type: integer
    ErrorDetail:
      type: object
      required:
        - code
        - message
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing, invalid, expired, revoked, or inactive API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key lacks scope or the creator lacks current permission for the
        requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    PublicApiKey:
      type: http
      scheme: bearer
      bearerFormat: ers_live API key
      description: >-
        Workspace API key created in Erstan Settings. Keys carry scopes
        (`agents:list`, `agents:read`, `agents:write`, `agents:run`,
        `runs:read`, `tasks:execute`, `documents:read`, `documents:write`,
        `files:read`, `files:write`). Agent access follows the key creator's
        current workspace, team, and agent permissions. Agent draft creation
        requires `agents:write`; update, validation, and publishing require both
        `agents:read` and `agents:write`; draft testing also requires
        `agents:run`. Keys with `tasks:execute` must include at least one
        allowed project or team (`allowedProjectIds` / `allowedTeamIds`); keys
        with document or file scopes must include at least one allowed team.
        Empty allowlists mean no access — the API fails closed.

````