> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-changeset-release-main.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`. Canonical creative-capability filters (`format_kind`, `publisher_domain`, `format_option_id`, `capability_id`, `creative_operation`) match any endpoint exposing that creative surface, including mixed sales/creative agents; add an explicit `type` only to narrow by primary registry classification.



## OpenAPI

````yaml https://agenticadvertising.org/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: >-
      Propose, review, 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.
  - name: Property Catalog
    description: >-
      Contribute facts to the property fact-graph: resolve identifiers to stable
      property_rids (which also contributes them, with provenance) and dispute
      catalog claims.
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`. Canonical creative-capability filters
        (`format_kind`, `publisher_domain`, `format_option_id`, `capability_id`,
        `creative_operation`) match any endpoint exposing that creative surface,
        including mixed sales/creative agents; add an explicit `type` only to
        narrow by primary registry classification.
      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; multiple values are
              AND'd (vendor must carry all named metrics). When combined with
              `accreditation`, a cross-product AND applies — each (metric_id,
              accreditation) pair must be covered by the same metrics element.
              Duplicate values are ignored. Maximum 20 unique values; maximum
              100 cross-product pairs. Implies `type=measurement`.
            example: attention_units
          required: false
          description: >-
            Measurement-vendor filter: exact match on
            `measurement.metrics[].metric_id`. Repeatable; multiple values are
            AND'd (vendor must carry all named metrics). When combined with
            `accreditation`, a cross-product AND applies — each (metric_id,
            accreditation) pair must be covered by the same metrics element.
            Duplicate values are ignored. Maximum 20 unique values; maximum 100
            cross-product pairs. 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; multiple values are AND'd. When
              combined with `metric_id`, a cross-product AND applies — see
              `metric_id` description. Duplicate values are ignored. Maximum 20
              unique values; maximum 100 cross-product pairs. 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; multiple values are AND'd. When
            combined with `metric_id`, a cross-product AND applies — see
            `metric_id` description. Duplicate values are ignored. Maximum 20
            unique values; maximum 100 cross-product pairs. 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:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: >-
              Canonical creative-capability filter: exact match on
              creative.supported_formats[].format.format_kind. Repeatable with
              OR semantics. Matches standalone creative agents and mixed-role
              endpoints.
            example: video_hosted
          required: false
          description: >-
            Canonical creative-capability filter: exact match on
            creative.supported_formats[].format.format_kind. Repeatable with OR
            semantics. Matches standalone creative agents and mixed-role
            endpoints.
          name: format_kind
          in: query
        - schema:
            type: string
            description: >-
              Canonical creative-capability filter: exact publisher_domain on
              the same supported-format entry. Pair with format_option_id to
              find endpoints claiming an exact publisher format.
            example: shorts.streamhaus.example
          required: false
          description: >-
            Canonical creative-capability filter: exact publisher_domain on the
            same supported-format entry. Pair with format_option_id to find
            endpoints claiming an exact publisher format.
          name: publisher_domain
          in: query
        - schema:
            type: string
            description: >-
              Canonical creative-capability filter: exact publisher
              format_option_id on the same supported-format entry.
            example: spotlight_video
          required: false
          description: >-
            Canonical creative-capability filter: exact publisher
            format_option_id on the same supported-format entry.
          name: format_option_id
          in: query
        - schema:
            type: string
            description: >-
              Canonical creative-capability filter: exact endpoint-local
              creative.supported_formats[].capability_id.
          required: false
          description: >-
            Canonical creative-capability filter: exact endpoint-local
            creative.supported_formats[].capability_id.
          name: capability_id
          in: query
        - schema:
            anyOf:
              - type: string
                enum:
                  - build
                  - validate
                  - preview
              - type: array
                items:
                  type: string
                  enum:
                    - build
                    - validate
                    - preview
            description: >-
              Canonical creative-capability filter: required supported operation
              on the same format entry. Repeatable with OR semantics.
            example: build
          required: false
          description: >-
            Canonical creative-capability filter: required supported operation
            on the same format entry. Repeatable with OR semantics.
          name: creative_operation
          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:
            supported_formats:
              type: array
              items:
                type: object
                properties:
                  capability_id:
                    type: string
                  format:
                    type: object
                    properties:
                      format_kind:
                        type: string
                      publisher_domain:
                        type: string
                      format_option_id:
                        type: string
                      params:
                        type: object
                        additionalProperties: {}
                    required:
                      - format_kind
                    additionalProperties: {}
                  operations:
                    type: array
                    items:
                      type: string
                      enum:
                        - build
                        - validate
                        - preview
                    minItems: 1
                required:
                  - format
                  - operations
                additionalProperties: {}
            can_generate:
              type: boolean
            can_validate:
              type: boolean
            can_preview:
              type: boolean
          required:
            - supported_formats
            - can_generate
            - can_validate
            - can_preview
          additionalProperties: {}
        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

````