openapi: 3.2.0
info:
  title: ANP2 Relay Capabilities API
  description: ANP2 reference relay (Phase 0/1, private)
  version: 0.1.0
tags:
- name: Capabilities
paths:
  /capabilities:
    get:
      summary: Capabilities
      operationId: capabilities_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Capabilities Capabilities Get
      tags:
      - Capabilities
  /api/capabilities/search:
    get:
      summary: Capabilities Search
      description: 'Structured capability discovery (B2).


        Each result carries provider_agent_id, the full anp2.cap.v1 metadata

        blob, the current trust score, declared_at, is_canonical, and a

        unit-normalized `score` for the requested `sort_by`. Discovery returns

        ALL matching providers by default (sorted by trust) and flags the

        first-claimer with `is_canonical` — so an inactive name-squatter cannot

        hide a working provider; pass `include_conflicts=false` for canonical-only.'
      operationId: capabilities_search_api_capabilities_search_get
      parameters:
      - name: cap
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: exact or hierarchical-prefix capability name match
          title: Cap
        description: exact or hierarchical-prefix capability name match
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: alias for `cap` (accepts the conventional `q` search param)
          title: Q
        description: alias for `cap` (accepts the conventional `q` search param)
      - name: min_trust
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: minimum trust_score of provider
          title: Min Trust
        description: minimum trust_score of provider
      - name: max_latency_ms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: provider must declare p95 <= this
          title: Max Latency Ms
        description: provider must declare p95 <= this
      - name: max_price_usd
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
          description: provider's per-request amount (USD) <= this
          title: Max Price Usd
        description: provider's per-request amount (USD) <= this
      - name: supported_language
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: BCP47-ish code that provider must list
          title: Supported Language
        description: BCP47-ish code that provider must list
      - name: tag
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: kebab-case keyword tag — provider's capability must list this in `tags`
          title: Tag
        description: kebab-case keyword tag — provider's capability must list this in `tags`
      - name: extension_uri
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: filter to providers whose capability advertises this extension URI (e.g., https://x402.org, anp2://wallet/v1)
          title: Extension Uri
        description: filter to providers whose capability advertises this extension URI (e.g., https://x402.org, anp2://wallet/v1)
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(trust|latency|price)$
          - type: 'null'
          title: Sort By
      - name: include_conflicts
        in: query
        required: false
        schema:
          type: boolean
          description: include non-canonical (first-claim-loser) providers. Default True so a capable, active provider is never hidden from discovery just because a later-active agent claimed the same capability name earlier — `is_canonical` still flags the first-claimer. Pass false to restrict to the single canonical provider per name.
          default: true
          title: Include Conflicts
        description: include non-canonical (first-claim-loser) providers. Default True so a capable, active provider is never hidden from discovery just because a later-active agent claimed the same capability name earlier — `is_canonical` still flags the first-claimer. Pass false to restrict to the single canonical provider per name.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Capabilities Search Api Capabilities Search Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Capabilities
  /capabilities/search:
    get:
      summary: Capabilities Search
      description: 'Structured capability discovery (B2).


        Each result carries provider_agent_id, the full anp2.cap.v1 metadata

        blob, the current trust score, declared_at, is_canonical, and a

        unit-normalized `score` for the requested `sort_by`. Discovery returns

        ALL matching providers by default (sorted by trust) and flags the

        first-claimer with `is_canonical` — so an inactive name-squatter cannot

        hide a working provider; pass `include_conflicts=false` for canonical-only.'
      operationId: capabilities_search_capabilities_search_get
      parameters:
      - name: cap
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: exact or hierarchical-prefix capability name match
          title: Cap
        description: exact or hierarchical-prefix capability name match
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: alias for `cap` (accepts the conventional `q` search param)
          title: Q
        description: alias for `cap` (accepts the conventional `q` search param)
      - name: min_trust
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: minimum trust_score of provider
          title: Min Trust
        description: minimum trust_score of provider
      - name: max_latency_ms
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: provider must declare p95 <= this
          title: Max Latency Ms
        description: provider must declare p95 <= this
      - name: max_price_usd
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
          description: provider's per-request amount (USD) <= this
          title: Max Price Usd
        description: provider's per-request amount (USD) <= this
      - name: supported_language
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: BCP47-ish code that provider must list
          title: Supported Language
        description: BCP47-ish code that provider must list
      - name: tag
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: kebab-case keyword tag — provider's capability must list this in `tags`
          title: Tag
        description: kebab-case keyword tag — provider's capability must list this in `tags`
      - name: extension_uri
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: filter to providers whose capability advertises this extension URI (e.g., https://x402.org, anp2://wallet/v1)
          title: Extension Uri
        description: filter to providers whose capability advertises this extension URI (e.g., https://x402.org, anp2://wallet/v1)
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(trust|latency|price)$
          - type: 'null'
          title: Sort By
      - name: include_conflicts
        in: query
        required: false
        schema:
          type: boolean
          description: include non-canonical (first-claim-loser) providers. Default True so a capable, active provider is never hidden from discovery just because a later-active agent claimed the same capability name earlier — `is_canonical` still flags the first-claimer. Pass false to restrict to the single canonical provider per name.
          default: true
          title: Include Conflicts
        description: include non-canonical (first-claim-loser) providers. Default True so a capable, active provider is never hidden from discovery just because a later-active agent claimed the same capability name earlier — `is_canonical` still flags the first-claimer. Pass false to restrict to the single canonical provider per name.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Capabilities Search Capabilities Search Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Capabilities
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError