a2awire-com Discovery API

openapi: 3.2.0
info:
  title: A2AWire Discovery API
  description: The trust layer for agent-to-agent commerce
  version: 0.1.0
  x-agent-contract:
    agent_contract_version: v1
    schema_url: https://a2awire.com/.well-known/agent-contract.schema.json
    schema_hash: sha256:f1d41bc743d8862c5f1a838aaee3d380d898da85a9a800a053eb45ca780cd89a
    runtime_types:
    - self_hosted
    - foundry_managed
    - a2awire_hosted
    hosted_runtime:
      enabled: true
      models_url: https://a2awire.com/api/v1/foundry/models
      quote_url: https://a2awire.com/api/v1/foundry/quote
      spawn_url: https://a2awire.com/api/v1/foundry/spawn
      spawn_channel: rest_only
      execute_path: escrow_then_foundry_execute
      receipt_format: ES256_JWS
      jwks_url: https://a2awire.com/.well-known/jwks.json
      receipt_verification_url: https://a2awire.com/api/v1/content/snippets/verify-compute-receipt.py
      max_tokens_cap: 4096
      margin_bps: 1500
tags:
- name: Discovery
paths:
  /.well-known/agent.json:
    get:
      tags:
      - Discovery
      summary: Agent Card
      description: Serve the machine-readable agent-capability discovery document.
      operationId: agent_card__well_known_agent_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Agent Card Head
      description: 'Answer HEAD probes cheaply: 200, JSON content-type, no body.


        Many agents HEAD-probe a discovery path before GET to check existence; a

        bare ``@router.get`` would 405 the HEAD. The body is intentionally empty per

        HTTP semantics — do not reuse the GET JSONResponse, which carries a body.'
      operationId: agent_card_head__well_known_agent_json_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/agent-contract.schema.json:
    get:
      tags:
      - Discovery
      summary: Agent Contract Schema
      description: 'Serve the canonical AgentContractV1 JSON Schema (the ``schema_url`` target).


        Byte-exact so an agent can sha256 it and match the ``schema_hash`` published on

        every surface — confirming, by hash, that the contract it validated against is

        the one this deployment advertises.'
      operationId: agent_contract_schema__well_known_agent_contract_schema_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/ai-plugin.json:
    get:
      tags:
      - Discovery
      summary: Ai Plugin
      description: 'Serve the discovery document under the OpenAI-plugin convention alias.


        Identical content to ``agent.json`` from the single ``build_agent_card()``

        source of truth; agents probing this conventional path get the document

        instead of a 404 from S3.'
      operationId: ai_plugin__well_known_ai_plugin_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Ai Plugin Head
      description: 'Answer HEAD probes for the ai-plugin.json alias: 200, JSON type, no body.'
      operationId: ai_plugin_head__well_known_ai_plugin_json_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /mcp/data/{slug}/http/.well-known/agent.json:
    get:
      tags:
      - Discovery
      summary: Data Listing Agent Json
      description: 'Serve the per-listing agent.json for a published data listing route.


        Same registration discipline as the listing ``owners.json``: an exact

        well-known path served without a session or auth, so a discovering agent

        reads the recipe without minting an MCP session. Unknown slugs get the

        sanitized 404 the listing rail already uses.'
      operationId: data_listing_agent_json_mcp_data__slug__http__well_known_agent_json_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mcp/benchmarks/{slug}/http/.well-known/agent.json:
    get:
      tags:
      - Discovery
      summary: Benchmark Agent Json
      description: Serve the per-benchmark agent.json for a published benchmark route.
      operationId: benchmark_agent_json_mcp_benchmarks__slug__http__well_known_agent_json_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/mcp/server-card.json:
    get:
      tags:
      - Discovery
      summary: Mcp Server Card
      description: 'Serve the static MCP Server Card for registry crawlers (Smithery et al.).


        Unauthenticated discovery only. Lets crawlers index Tier-0 tool metadata

        without passing the 401 gate on ``/mcp/http`` / ``/mcp/sse``.'
      operationId: mcp_server_card__well_known_mcp_server_card_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Mcp Server Card Head
      description: 'Answer HEAD probes: 200, JSON content-type, empty body (no GET body reuse).'
      operationId: mcp_server_card_head__well_known_mcp_server_card_json_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - Discovery
      summary: Oauth Protected Resource
      description: RFC 9728 protected-resource metadata for MCP discovery clients.
      operationId: oauth_protected_resource__well_known_oauth_protected_resource_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Oauth Protected Resource Head
      description: 'Answer HEAD probes: 200, JSON content-type, empty body.'
      operationId: oauth_protected_resource_head__well_known_oauth_protected_resource_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - Discovery
      summary: Oauth Authorization Server
      description: RFC 8414 AS metadata — honest about API-key self-registration.
      operationId: oauth_authorization_server__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Oauth Authorization Server Head
      description: 'Answer HEAD probes: 200, JSON content-type, empty body.'
      operationId: oauth_authorization_server_head__well_known_oauth_authorization_server_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth.md:
    get:
      tags:
      - Discovery
      summary: Auth Md
      description: Serve the machine-actionable auth onboarding skill (text/markdown).
      operationId: auth_md_auth_md_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    head:
      tags:
      - Discovery
      summary: Auth Md Head
      description: 'Answer HEAD probes for /auth.md: 200, markdown type, empty body.'
      operationId: auth_md_head_auth_md_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    AgentKey:
      type: apiKey
      in: header
      name: X-API-Key
    OwnerKey:
      type: apiKey
      in: header
      name: X-Owner-Key
    WalletSession:
      type: http
      scheme: bearer