> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List agents

> List all agents in the registry. Optionally enrich with health checks, capabilities, and property summaries via query parameters. Measurement-vendor filters (`metric_id`, `accreditation`, `q`) imply `type=measurement` when `type` is unset; an explicit `type` other than `measurement` returns 400.



## OpenAPI

````yaml /static/openapi/registry.yaml get /api/registry/agents
openapi: 3.1.0
info:
  title: AgenticAdvertising.org Registry API
  description: >-
    REST API for the AgenticAdvertising.org registry. Resolve brands,

    discover properties, look up agents, and validate authorization in the

    AdCP ecosystem.


    Most endpoints are public and require no authentication. Endpoints marked

    with a lock icon accept either an organization API key or a user JWT

    obtained via the OAuth 2.1 flow — see
    [Authentication](https://agenticadvertising.org/docs/registry/index#authentication).


    **Base URL:** `https://agenticadvertising.org`
  version: 1.0.0
  contact:
    name: AgenticAdvertising.org
    url: https://agenticadvertising.org
servers:
  - url: https://agenticadvertising.org
    description: Production
security: []
tags:
  - name: Onboarding
    description: >-
      Explicitly bootstrap a third-party integration into the AAO registry. Most
      callers don't need this tag — `POST /api/me/agents` auto-creates the org
      (for fresh users) and the member profile (for first-time agent
      registration) without a separate round trip. Use `POST /api/organizations`
      only when you need to override the auto-derived org name / company_type /
      revenue_tier. Tier transitions happen via the billing flow only; the
      Stripe webhook is the sole writer of `organizations.membership_tier`.
  - name: Member Agents
    description: >-
      Register, list, update, and remove agents on the caller's organization
      member profile. Authenticated programmatic surface for CI / scripts that
      don't want to round-trip the full member profile.
  - name: Brand Resolution
    description: Resolve advertiser domains to canonical brand identities.
  - name: Property Resolution
    description: >-
      Resolve publisher domains to their property configurations and authorized
      agents.
  - name: Agent Discovery
    description: >-
      Browse the federated agent network, search agent inventory profiles,
      publisher index, and registry statistics.
  - name: Change Feed
    description: Poll cursor-based registry change events for local sync.
  - name: Lookups & Authorization
    description: >-
      Look up agents by domain or property, and validate ad-serving
      authorization.
  - name: Validation Tools
    description: >-
      Validate publisher adagents.json files and generate compliant
      configurations.
  - name: Community Mirrors
    description: >-
      Publish, fetch, list, and retire catalog-only adagents.json mirrors for
      platforms that have not adopted AdCP.
  - name: Search
    description: Cross-entity search across brands, publishers, agents, and properties.
  - name: Agent Probing
    description: >-
      Connect to live agents and inspect their capabilities, formats, and
      inventory.
  - name: Brand Discovery
    description: Discover and crawl brand.json files across domains.
  - name: Agent Compliance
    description: Agent compliance status, storyboard test results, and compliance history.
  - name: Policy Registry
    description: >-
      Browse, resolve, and contribute governance policies for campaign
      compliance.
paths:
  /api/registry/agents:
    get:
      tags:
        - Agent Discovery
      summary: List agents
      description: >-
        List all agents in the registry. Optionally enrich with health checks,
        capabilities, and property summaries via query parameters.
        Measurement-vendor filters (`metric_id`, `accreditation`, `q`) imply
        `type=measurement` when `type` is unset; an explicit `type` other than
        `measurement` returns 400.
      operationId: listAgents
      parameters:
        - schema:
            type: string
            enum:
              - brand
              - rights
              - measurement
              - governance
              - creative
              - sales
              - buying
              - signals
              - unknown
          required: false
          name: type
          in: query
        - schema:
            type: string
            enum:
              - 'true'
          required: false
          name: health
          in: query
        - schema:
            type: string
            enum:
              - 'true'
          required: false
          name: capabilities
          in: query
        - schema:
            type: string
            enum:
              - 'true'
          required: false
          name: properties
          in: query
        - schema:
            type: string
            enum:
              - 'true'
          required: false
          name: compliance
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: >-
              Measurement-vendor filter: exact match on
              `measurement.metrics[].metric_id`. Repeatable (each value is OR'd
              within the param, AND'd with other filters). Implies
              `type=measurement`.
            example: attention_units
          required: false
          description: >-
            Measurement-vendor filter: exact match on
            `measurement.metrics[].metric_id`. Repeatable (each value is OR'd
            within the param, AND'd with other filters). Implies
            `type=measurement`.
          name: metric_id
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: >-
              Measurement-vendor filter: exact match on
              `measurement.metrics[].accreditations[].accrediting_body` (e.g.
              `MRC`, `JIC`, `ARF`). Repeatable. Implies `type=measurement`.
              Accreditation claims are vendor-asserted; AAO does not
              independently verify (`verified_by_aao` is always `false` in the
              response).
            example: MRC
          required: false
          description: >-
            Measurement-vendor filter: exact match on
            `measurement.metrics[].accreditations[].accrediting_body` (e.g.
            `MRC`, `JIC`, `ARF`). Repeatable. Implies `type=measurement`.
            Accreditation claims are vendor-asserted; AAO does not independently
            verify (`verified_by_aao` is always `false` in the response).
          name: accreditation
          in: query
        - schema:
            type: string
            maxLength: 64
            description: >-
              Measurement-vendor filter: case-insensitive substring match
              against `measurement.metrics[].metric_id`. v1 scope: metric_id
              only (description/standard search is a follow-up). Max 64 chars;
              SQL wildcard characters are escaped. Implies `type=measurement`.
            example: attention
          required: false
          description: >-
            Measurement-vendor filter: case-insensitive substring match against
            `measurement.metrics[].metric_id`. v1 scope: metric_id only
            (description/standard search is a follow-up). Max 64 chars; SQL
            wildcard characters are escaped. Implies `type=measurement`.
          name: q
          in: query
        - schema:
            type: array
            items:
              type: string
              enum:
                - spec
                - live
            description: >-
              Filter to agents whose active badge covers the given verification
              axis. Repeat the parameter for AND semantics:
              ?verification_mode=spec&verification_mode=live returns only agents
              verified on both axes.
          required: false
          description: >-
            Filter to agents whose active badge covers the given verification
            axis. Repeat the parameter for AND semantics:
            ?verification_mode=spec&verification_mode=live returns only agents
            verified on both axes.
          name: verification_mode
          in: query
        - schema:
            type: string
            enum:
              - 'true'
            description: >-
              When true, filter to agents that hold any active verification
              badge.
          required: false
          description: When true, filter to agents that hold any active verification badge.
          name: verified
          in: query
      responses:
        '200':
          description: Agent list
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/FederatedAgentWithDetails'
                  count:
                    type: integer
                required:
                  - agents
                  - count
        '400':
          description: Invalid query parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  valid_values:
                    type: array
                    items:
                      type: string
                required:
                  - error
components:
  schemas:
    FederatedAgentWithDetails:
      type: object
      properties:
        url:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - brand
            - rights
            - measurement
            - governance
            - creative
            - sales
            - buying
            - signals
            - unknown
        protocol:
          type: string
          enum:
            - mcp
            - a2a
        description:
          type: string
        mcp_endpoint:
          type: string
        contact:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            website:
              type: string
          required:
            - name
            - email
            - website
        added_date:
          type: string
        member:
          type: object
          properties:
            slug:
              type: string
            display_name:
              type: string
            membership_tier:
              type: string
              description: >-
                Raw AAO membership tier enum (e.g. `individual_professional`,
                `company_leader`). Present only when the profile owner has set
                their member card to public (`is_public=true`) AND the org has a
                resolvable tier. Absent for private profiles and for orgs
                without an active tier-bearing subscription.
            membership_tier_label:
              type: string
              description: >-
                Human-readable label for `membership_tier` (e.g. `Professional`,
                `Partner`, `Leader`). Matches the AAO pricing page. Use this for
                UI display; the raw enum is for programmatic gating. Presence
                rules match `membership_tier`.
            is_founding_member:
              type: boolean
              description: >-
                True when the profile owner carries the Founding Member badge
                (joined before the founding-cohort cutoff). Surfaced when the
                profile owner has set their member card to public
                (`is_public=true`). Absent for private profiles. Founding Member
                is orthogonal to tier — founding orgs typically display both
                (e.g. Scope3 shows `Partner` + `Founding Member`).
          description: >-
            AAO member that owns this agent record. The registry contains only
            agents that members have explicitly enrolled on their member
            profile.
        health:
          $ref: '#/components/schemas/AgentHealth'
        stats:
          $ref: '#/components/schemas/AgentStats'
        capabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        compliance:
          $ref: '#/components/schemas/AgentCompliance'
        publisher_domains:
          type: array
          items:
            type: string
        property_summary:
          $ref: '#/components/schemas/PropertySummary'
      required:
        - url
        - name
        - type
    AgentHealth:
      type: object
      properties:
        online:
          type: boolean
        checked_at:
          type: string
        response_time_ms:
          type: number
        tools_count:
          type: integer
        resources_count:
          type: integer
        error:
          type: string
      required:
        - online
        - checked_at
    AgentStats:
      type: object
      properties:
        property_count:
          type: integer
        publisher_count:
          type: integer
        publishers:
          type: array
          items:
            type: string
        creative_formats:
          type: integer
    AgentCapabilities:
      type: object
      properties:
        tools_count:
          type: integer
        tools:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
            required:
              - name
              - description
        standard_operations:
          type: object
          properties:
            can_search_inventory:
              type: boolean
            can_get_availability:
              type: boolean
            can_reserve_inventory:
              type: boolean
            can_get_pricing:
              type: boolean
            can_create_order:
              type: boolean
            can_list_properties:
              type: boolean
          required:
            - can_search_inventory
            - can_get_availability
            - can_reserve_inventory
            - can_get_pricing
            - can_create_order
            - can_list_properties
        creative_capabilities:
          type: object
          properties:
            formats_supported:
              type: array
              items:
                type: string
            can_generate:
              type: boolean
            can_validate:
              type: boolean
            can_preview:
              type: boolean
          required:
            - formats_supported
            - can_generate
            - can_validate
            - can_preview
        signals_capabilities:
          type: object
          properties:
            audience_types:
              type: array
              items:
                type: string
            can_match:
              type: boolean
            can_activate:
              type: boolean
            can_get_signals:
              type: boolean
          required:
            - audience_types
            - can_match
            - can_activate
            - can_get_signals
        measurement_capabilities:
          type: object
          properties:
            metrics:
              type: array
              items:
                type: object
                properties:
                  metric_id:
                    type: string
                  standard_reference:
                    type: string
                  accreditations:
                    type: array
                    items:
                      type: object
                      properties:
                        accrediting_body:
                          type: string
                        certification_id:
                          type: string
                        valid_until:
                          type: string
                        evidence_url:
                          type: string
                        verified_by_aao:
                          type: boolean
                          enum:
                            - false
                          description: >-
                            Always `false` — accreditation claims are
                            vendor-asserted. AAO does not independently verify;
                            renderers should mark these as vendor claims.
                      required:
                        - accrediting_body
                        - verified_by_aao
                  unit:
                    type: string
                  description:
                    type: string
                  methodology_url:
                    type: string
                  methodology_version:
                    type: string
                required:
                  - metric_id
          required:
            - metrics
          description: >-
            Vendor-published per-metric catalog for measurement agents.
            Populated when the crawler successfully fetched and validated
            `get_adcp_capabilities.measurement` (AdCP 3.x). Mirrors the protocol
            shape — see the AdCP `get_adcp_capabilities` reference for field
            semantics.
      required:
        - tools_count
    AgentCompliance:
      type: object
      properties:
        status:
          type: string
          enum:
            - passing
            - degraded
            - failing
            - unknown
        requested_compliance_target:
          type:
            - string
            - 'null'
          description: >-
            Requested compliance target before alias resolution, e.g. 3.0 or
            3.1-beta.
        adcp_version:
          type:
            - string
            - 'null'
          description: >-
            Concrete AdCP compliance bundle version used for the latest run,
            e.g. 3.0.12.
        lifecycle_stage:
          type: string
          enum:
            - development
            - testing
            - production
            - deprecated
        tracks:
          type: object
          additionalProperties:
            type: string
          example:
            core: pass
            products: fail
        track_details:
          type: array
          items:
            type: object
            properties:
              track:
                type: string
              status:
                type: string
              scenario_count:
                type: integer
              passed_count:
                type: integer
              duration_ms:
                type: number
              has_coverage_gap_skip:
                type: boolean
            required:
              - track
              - status
              - scenario_count
              - passed_count
              - duration_ms
          description: >-
            Latest-run per-track summary. Skipped tracks with
            has_coverage_gap_skip=true represent selected coverage gaps, such as
            missing_test_controller.
        streak_days:
          type: integer
        last_checked_at:
          type:
            - string
            - 'null'
        headline:
          type:
            - string
            - 'null'
        monitoring_paused:
          type: boolean
        check_interval_hours:
          type: integer
        verified:
          type: boolean
        verified_roles:
          type: array
          items:
            type: string
            enum:
              - media-buy
              - signals
              - governance
              - creative
              - brand
              - sponsored-intelligence
              - measurement
          description: >-
            AdCP protocols the agent is AAO Verified for (e.g. media-buy,
            creative). Matches enums/adcp-protocol.json.
      required:
        - status
        - lifecycle_stage
        - tracks
        - streak_days
        - last_checked_at
        - headline
    PropertySummary:
      type: object
      properties:
        total_count:
          type: integer
        count_by_type:
          type: object
          additionalProperties:
            type: integer
        tags:
          type: array
          items:
            type: string
        publisher_count:
          type: integer
      required:
        - total_count
        - count_by_type
        - tags
        - publisher_count

````