Averray Verify API

openapi: 3.2.0
info:
  title: Averray HTTP Verify API
  version: 0.2.0
  description: Public discovery, standalone Verify, and wallet-authenticated buyer and worker operations. Work and accounts settle on Polkadot Hub mainnet; paid Verify uses Base USDC. Operator/admin and session-settlement verifier operations are intentionally excluded. Read live discovery for availability and payment terms.
servers:
- url: https://api.averray.com
  description: Public mainnet API
tags:
- name: Verify
  description: Standalone verification; discover profiles and payment terms live.
paths:
  /verify/profiles:
    get:
      tags:
      - Verify
      operationId: listVerificationProfiles
      summary: List immutable verification profiles
      description: Read profiles[].workedExample.request and profile-specific input schemas, limits, availability and live Base USDC price. A profile's version must be pinned in the run request.
      security: []
      responses:
        '200':
          description: List immutable verification profiles
          content:
            application/json:
              schema:
                type: object
                required:
                - profiles
                properties:
                  profiles:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        version:
                          type: integer
                        ref:
                          type: string
                        status:
                          type: string
                        availability:
                          type: object
                          additionalProperties: true
                        price:
                          type: object
                          additionalProperties: true
                        limits:
                          type: object
                          additionalProperties: true
                        workedExample:
                          type: object
                          additionalProperties: true
                      additionalProperties: true
                additionalProperties: true
  /verify/runs:
    get:
      tags:
      - Verify
      operationId: verifyRunCreationMethod
      summary: Discover the required method for creating a Verify run
      responses:
        '405':
          description: Run creation requires POST; GET never creates or bills a run.
          headers:
            Allow:
              schema:
                type: string
                const: POST
    post:
      tags:
      - Verify
      operationId: createVerificationRun
      summary: Create a standalone verification run
      description: Send a valid profile/version/target/inputs body without payment to obtain the request-bound 402 challenge. An unpaid POST with no body or an empty JSON object returns the published URL-only MCP example's discovery challenge without creating or reserving a run. Non-empty invalid bodies and empty bodies with payment proof remain 400. Before purchasing, supply your actual input and obtain its fresh challenge; retry that identical body with PAYMENT-SIGNATURE containing the signed accepts[0] requirements. Payment is Base USDC only; no worker SIWE session is needed. 200 may mean queued, not complete. Poll the public run URL. Approved/rejected runs capture the fee; inconclusive and platform_fault runs are never billed.
      security: []
      parameters:
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        description: Base64 x402 payment proof from the preceding challenge. X-PAYMENT and verification-payment are compatibility aliases.
        schema:
          type: string
      - name: Verification-Target-Authorization
        in: header
        required: false
        description: Bearer scoped target credential for the MCP profile only. Ephemeral for this run; never persist it in the request body or receipt.
        schema:
          type: string
      requestBody:
        required: false
        description: A complete VerifyRunRequest is required to create a run. An absent body or empty object is accepted only without payment, for a discovery-only 402.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/VerifyRunRequest'
              - type: object
                maxProperties: 0
                additionalProperties: false
      responses:
        '200':
          description: Create a standalone verification run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyRun'
        '400':
          description: Invalid request or profile input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Base payment requirements with PAYMENT-REQUIRED. Complete valid input yields a request-bound challenge; absent/empty unpaid input yields the published example's discovery challenge. Obtain a fresh challenge for actual input before paying. Admission refuses validBefore > now + maxTimeoutSeconds + 300 with payment_authorization_window_too_long and details.action sign_fresh_authorization. A signed payer with Base USDC balance below the authorized amount receives payment_insufficient_balance with details.action fund_wallet_or_sign_fresh_authorization; no run or reservation is created.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 challenge.
              schema:
                type: string
        '404':
          description: Unknown profile/version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'payment_authorization_in_use: this Base USDC payer/nonce is already reserved. For a new purchase, sign a fresh authorization with a new nonce (details.action: sign_fresh_authorization). Does not reveal the owning runId or claim customerFunds unchanged: the owning run may still capture. Same-request replays return the existing run while the reservation remains, through validBefore + 24 hours.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Run intake rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'Payment or execution capability unavailable. payment_domain_unavailable means the configured EIP-712 domain is not yet validated: details.status unavailable, details.retryable true for transport errors/timeouts or false for deterministic identity mismatches, Cache-Control no-store. Transient failures retry in the background and on requests after the shared backoff deadline, with Retry-After on the 503; requests inside the window make no provider calls. Requests sharing an in-flight hung domain read may wait up to 8 seconds; recovery can take up to 8 seconds in flight plus a 30-second backoff window; no 402 without requirements is emitted. Each admission getBlockNumber, authorizationState and balanceOf read has an 8-second deadline. A timeout returns payment_chain_read_timeout with details.reason base_block_read_timeout, base_nonce_state_read_timeout or base_balance_read_timeout and details.action retry_when_base_reads_recover. payment_block_unavailable with details.reason base_block_read_failed means the Base admission checkpoint could not be read; no run is admitted. payment_balance_unavailable means the Base USDC balance read failed: details.reason base_balance_read_failed, details.action retry_when_base_reads_recover. No run or reservation is created; a failed read never admits work.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /verify/runs/{runId}:
    get:
      tags:
      - Verify
      operationId: getVerificationRun
      summary: Poll a public verification run
      description: No authentication required. Opaque run id returned by POST /verify/runs. Inspect status, verdict, billing and receipt; queued is not a completed purchase.
      security: []
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Poll a public verification run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyRun'
        '404':
          description: Unknown verification run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    VerifyRunRequest:
      type: object
      required:
      - profile
      - profileVersion
      - target
      - inputs
      properties:
        profile:
          type: string
          minLength: 1
          description: profiles[].name from GET /verify/profiles.
        profileVersion:
          type: integer
          minimum: 1
        target:
          type: object
          additionalProperties: true
          description: Profile-specific target; use the published input schema and worked example.
        inputs:
          type: object
          additionalProperties: true
          description: Profile-specific inputs. Never place target credentials here.
      additionalProperties: false
    VerifyRun:
      type: object
      required:
      - runId
      - profile
      - profileVersion
      - status
      - billing
      - billingRule
      properties:
        runId:
          type: string
        profile:
          type: string
        profileVersion:
          type: integer
        profileRef:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - executed
          - complete
        submittedAt:
          type: string
          format: date-time
        billingRule:
          type: string
          description: Live Verify billing rule, also advertised at resources[0].billingRule in x402 discovery.
        billing:
          type: object
          required:
          - status
          properties:
            status:
              type: string
              enum:
              - authorized
              - capturing
              - captured
              - not_captured
            amountRaw:
              type: string
              pattern: ^[0-9]+$
            asset:
              type: string
            network:
              type: string
            transactionHash:
              type: string
          additionalProperties: true
        verdict:
          type: object
          description: 'Recovering captures expose no decisive verdict. Terminal unbilled recovery reasons: payment_cancelled_by_payer, payment_authorization_used_elsewhere, payment_authorization_expired; each has outcome inconclusive.'
          additionalProperties: true
        receipt:
          type: object
          additionalProperties: true
        receiptId:
          type: string
        asyncStatus:
          type: object
          additionalProperties: true
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
        code:
          type: string
          description: Compatibility error-code field used by a small number of conflict responses.
        message:
          type: string
        details:
          description: Optional structured context for validation, authentication, or conflict failures.
        requestId:
          type: string
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT