VouchSpec Agent Skill Evidence API

# Faithful YAML rendering of https://vouchspec.plyrium.com/openapi.json (fetched 2026-09-19, HTTP 200,
# application/json; byte-identical alias at /.well-known/openapi.json). Verbatim JSON in _original/.
# No operations, schemas or servers were added or removed. Ownership: servers[] vouchspec.plyrium.com,
# info.termsOfService www.plyrium.com/vouchspec/policies, agent card provider.organization 'Plyrium'.
openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: VouchSpec Agent Skill Evidence API
  version: 0.1.0
  description: Agent-only API for purchasing fresh, isolated static validation and signed evidence for one exact immutable
    public GitHub Agent Skill commit. There is no human checkout.
  termsOfService: https://www.plyrium.com/vouchspec/policies
externalDocs:
  description: VouchSpec machine discovery contract
  url: https://vouchspec.plyrium.com/api/vouchspec/v1/discovery
servers:
- url: https://vouchspec.plyrium.com
  description: Base mainnet commerce
tags:
- name: Discovery
  description: Free, anonymous machine-readable service metadata.
- name: Purchase
  description: x402-paid exact-commit validation intake.
- name: Verification
  description: Public receipt bytes, status, and issuer key.
x-vouchspec:
  agentOnly: true
  humanCheckout: false
  profile: vouchspec-public-static-v1
  operation: fresh_public_static_validation
  payment:
    protocol: x402
    version: 2
    scheme: exact
    network: eip155:8453
    asset: USDC
    amount: '0.25'
    atomicAmount: '250000'
  ardCatalog: https://vouchspec.plyrium.com/.well-known/ai-catalog.json
  fulfillment:
    accepted_input: immutable_public_github_coordinates
    artifact_uploads: false
    private_repositories: false
    artifact_code_executed: false
    inspection_worker_egress: false
    signer_egress: false
    expected_delivery_minutes: 10
paths:
  /api/vouchspec/v1/health:
    get:
      tags:
      - Discovery
      operationId: getVouchSpecHealth
      summary: Check whether commerce is operational
      responses:
        '200':
          description: VouchSpec is operational.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/vouchspec/v1/discovery:
    get:
      tags:
      - Discovery
      operationId: getVouchSpecDiscovery
      summary: Get the canonical VouchSpec machine contract
      responses:
        '200':
          description: Current endpoints, schemas, payment terms, and receipt rules.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          $ref: '#/components/responses/Unavailable'
  /.well-known/x402:
    get:
      tags:
      - Discovery
      operationId: getVouchSpecX402Manifest
      summary: Get the x402 payment manifest
      responses:
        '200':
          description: Current x402 endpoint and payment requirement metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/vouchspec/v1/validate:
    get:
      tags:
      - Discovery
      operationId: getVouchSpecValidationService
      summary: Check the validation service and discover its paid POST operation
      description: Read-only health and payment-discovery metadata. This operation never verifies or settles a payment.
      responses:
        '200':
          description: The agent-only validation service is ready.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          $ref: '#/components/responses/Unavailable'
      x-vouchspec-side-effects: None. Payment is accepted only by POST.
    post:
      tags:
      - Purchase
      operationId: purchaseExactCommitValidation
      summary: Purchase validation for one exact public Agent Skill commit
      description: Send the strict validation request without PAYMENT-SIGNATURE to receive the canonical 402 challenge. Authorize
        exactly that challenge, then retry the identical request with PAYMENT-SIGNATURE. An exactly empty unpaid probe is
        also accepted for challenge discovery; a paid request always requires the body.
      parameters:
      - $ref: '#/components/parameters/PaymentSignature'
      requestBody:
        required: false
        description: Required for every purchase and payment retry; optional only for an empty unpaid challenge probe.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
      responses:
        '200':
          description: Payment settled. One-time bearer credentials and delivery endpoints are returned.
          headers:
            PAYMENT-RESPONSE:
              description: Base64-encoded x402 settlement response.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaidValidationAccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: Payment is required. Authorize the exact challenge and retry the identical request.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 v2 payment requirements.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/TooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
      x-x402:
        version: 2
        scheme: exact
        network: eip155:8453
        asset: USDC
        amountAtomic: '250000'
        manifest: https://vouchspec.plyrium.com/.well-known/x402
      x-vouchspec-side-effects: Payment settlement and asynchronous isolated validation after a valid paid retry.
  /api/vouchspec/v1/keys/issuer:
    get:
      tags:
      - Verification
      operationId: getVouchSpecIssuerKey
      summary: Get the current Ed25519 receipt-verification key
      responses:
        '200':
          description: Public issuer key and key identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuerKey'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/vouchspec/v1/receipts/{sha256_hex}:
    get:
      tags:
      - Verification
      operationId: getVouchSpecReceipt
      summary: Fetch immutable DSSE receipt bytes by SHA-256 digest
      parameters:
      - $ref: '#/components/parameters/Sha256Hex'
      responses:
        '200':
          description: Exact immutable DSSE envelope bytes.
          content:
            application/vnd.dsse.envelope.v1+json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/vouchspec/v1/receipts/{sha256_hex}/status:
    get:
      tags:
      - Verification
      operationId: getVouchSpecReceiptStatus
      summary: Check the live reliance status for a receipt
      description: Fetch this no-store status before every new reliance decision; cached receipt bytes alone are insufficient.
      parameters:
      - $ref: '#/components/parameters/Sha256Hex'
      responses:
        '200':
          description: Current receipt lifecycle status.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    PaymentSignature:
      name: PAYMENT-SIGNATURE
      in: header
      required: false
      description: Base64-encoded x402 v2 authorization supplied only on the paid retry.
      schema:
        type: string
        maxLength: 16384
    Sha256Hex:
      name: sha256_hex
      in: path
      required: true
      description: 'Lowercase SHA-256 digest of the exact DSSE envelope bytes, without the sha256: prefix.'
      schema:
        type: string
        pattern: ^[0-9a-f]{64}$
  schemas:
    ValidationRequest:
      type: object
      additionalProperties: false
      required:
      - schema_version
      - operation
      - source
      - profile
      - max_price
      - delivery_id
      properties:
        schema_version:
          const: 1.0.0
        operation:
          const: fresh_public_static_validation
        source:
          type: object
          additionalProperties: false
          required:
          - host
          - owner
          - repository
          - commit
          - skill_path
          properties:
            host:
              const: github.com
            owner:
              type: string
              pattern: ^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$
            repository:
              type: string
              pattern: ^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})$
            commit:
              type: string
              pattern: ^[0-9a-f]{40}$
            skill_path:
              type: string
              minLength: 1
              maxLength: 1024
        profile:
          const: vouchspec-public-static-v1
        max_price:
          type: object
          additionalProperties: false
          required:
          - currency
          - amount_minor
          properties:
            currency:
              const: usd
            amount_minor:
              type: integer
              minimum: 25
              maximum: 1000000
        delivery_id:
          type: string
          pattern: ^[A-Za-z0-9_-]{8,64}$
    PaidValidationAccess:
      type: object
      additionalProperties: false
      required:
      - schema_version
      - order
      - credentials
      - endpoints
      - payment
      properties:
        schema_version:
          const: 1.0.0
        order:
          type: object
          additionalProperties: true
        credentials:
          type: object
          additionalProperties: false
          required:
          - tenant_api_key
          - delivery_token
          - delivery_token_expires_at
          - notice
          properties:
            tenant_api_key:
              type: string
              description: Secret bearer capability shown once.
            delivery_token:
              type: string
              description: Secret delivery capability shown once.
            delivery_token_expires_at:
              type: string
              format: date-time
            notice:
              type: string
        endpoints:
          type: object
          additionalProperties: true
        payment:
          type: object
          additionalProperties: true
    IssuerKey:
      type: object
      additionalProperties: false
      required:
      - schema_version
      - key_id
      - algorithm
      - public_key_jwk
      - use
      properties:
        schema_version:
          const: '1.0'
        key_id:
          type: string
        algorithm:
          const: Ed25519
        public_key_jwk:
          type: object
          additionalProperties: true
        use:
          type: string
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: Malformed or invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Cross-site mutation rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooLarge:
      description: Request body exceeds the bounded intake limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Request rate exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: VouchSpec is temporarily unavailable.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'