Physical Capability Cloud Discovery API

openapi: 3.2.0
info:
  title: Physical Capability Cloud Gateway Discovery API
  version: 0.1.0
  description: Agent-native API for discovering and invoking physical capabilities. See https://capability.network/agent-package.json for the 254-tool agent package.
servers:
- url: https://capability.network
tags:
- name: Discovery
paths:
  /.well-known/ai-catalog.json:
    get:
      operationId: get_well_known_ai_catalog_json
      summary: AI Catalog for PCC's live physical capabilities
      tags:
      - Discovery
      description: Generates an Agentic Resource Discovery AI Catalog from PCC's canonical capability-type registry at request time.
      responses:
        '200':
          description: Default Response
  /.well-known/agent-directory.json:
    get:
      operationId: get_well_known_agent_directory_json
      summary: PCC physical-capability agent directory
      tags:
      - Discovery
      description: Lists PCC's physical-capability discovery agent and its real discovery and A2A endpoints.
      responses:
        '200':
          description: Default Response
  /.well-known/mcp-registry-auth:
    get:
      operationId: get_well_known_mcp_registry_auth
      summary: MCP Registry domain-ownership proof
      tags:
      - Discovery
      description: Ed25519 public-key record so PCC can publish to the official MCP Registry via HTTP domain authentication.
      responses:
        '200':
          description: Default Response
  /ask:
    post:
      operationId: post_ask
      summary: Search PCC capabilities with an NLWeb-compatible query
      tags:
      - Discovery
      description: 'Accepts either {query: string} or NLWeb 0.55 {query: {text: string}} and searches the live PCC capability catalog.'
      responses:
        '200':
          description: Default Response
  /api/capabilities/types:
    get:
      operationId: get_api_capabilities_types
      summary: List all capability types the network offers (templates + registered + CSD)
      tags:
      - Discovery
      description: Returns the union of built-in template types, distinct types registered in the catalog (including ad-hoc types with no compile-time template), and CSD-described types — deduped and sorted (e.g. 3d-printing, cnc, hplc, laser-cutting, wood-fired-pizza). PUBLIC — no auth required. Per-template detail lives at /api/capabilities/templates.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  types:
                    type: array
                    items:
                      type: string
                required:
                - types
  /api/capabilities/templates:
    get:
      operationId: get_api_capabilities_templates
      summary: List capability templates with pricing hints
      tags:
      - Discovery
      description: Returns the structural template for each registered capability type, including parameter group counts and base pricing hints. Use this to build a UI selector before calling /api/build/options.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  templates:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        capabilityType:
                          type: string
                        name:
                          type: string
                        version:
                          type: string
                        description:
                          type: string
                        paramCount:
                          type: integer
                        groups:
                          type: array
                          items:
                            type: string
                        basePrice:
                          type: number
                        currency:
                          type: string
  /api/capabilities:
    get:
      operationId: get_api_capabilities
      summary: List capability instances (paginated, optionally filtered by type)
      tags:
      - Discovery
      description: Returns a paginated set of CapabilityDTO records spanning all registered kernels. Each record includes type, materials, tolerances, pricing, location, plus enrichment fields (reputation, queueDepth, available, kernelStatus). PUBLIC. Optional ?type= narrows the set. The match is BOTH exact (`type=pizza.order` returns only `pizza.order` caps) and prefix-based (`type=courier` returns `courier.dispatch`, `courier.quote`, `courier.track`, etc.). This lets agents query by a coarse scope (`courier`, `pizza`, `compute`, `manufacturing`, `lab`, `food`, `software-service`, `sensor`, `robot`, `custom`) without hard-coding the vendor-specific suffixes. The list endpoint is the discovery surface — driver/operator agents poll it to find jobs they can claim, so filtering must be honoured.
      parameters:
      - schema:
          type: integer
          minimum: 0
          default: 0
        in: query
        name: offset
        required: false
      - schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        in: query
        name: limit
        required: false
      - schema:
          type: string
          minLength: 1
          maxLength: 128
        in: query
        name: type
        required: false
        description: Filter by capability type. Matches either exactly (`pizza.order`) or by prefix (`courier` => all `courier.*`).
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  hasMore:
                    type: boolean
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: PCC API key (pcc_live_...). Provision at POST /api/auth/provision.
x-payment-info:
  description: Machine-payment metadata for deployment-configured paid routes. MPP is the current default; x402 v2 remains a real legacy opt-in transport.
  discovery: https://capability.network/api/x402/routes
  x402:
    version: 2
    status: legacy-opt-in
    network: eip155:84532
    currency: USDC
    requestHeader: PAYMENT-SIGNATURE
    challengeHeader: PAYMENT-REQUIRED
  mpp:
    status: default-when-configured
    challengeHeader: WWW-Authenticate
    credentialHeader: Authorization