Averray Receipts API

openapi: 3.2.0
info:
  title: Averray HTTP Receipts 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: Receipts
  description: Public content-addressed receipts and signed-in history.
paths:
  /receipts:
    get:
      tags:
      - Receipts
      operationId: listOwnReceipts
      summary: List the signed-in wallet's receipts
      description: Newest-first own receipt history; querying another wallet is refused.
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: List the signed-in wallet's receipts
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /receipts/{receiptId}:
    get:
      tags:
      - Receipts
      operationId: getReceipt
      summary: Read a content-addressed receipt
      description: Exact receipt id wins. Session and job aliases redirect with 301 to the canonical id; unknown ids return 404. Public response includes serve-time presentation fields without rewriting the stored document.
      security: []
      parameters:
      - name: receiptId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Receipt response envelope. Verify document only; unsignedPresentation is not signed.
          content:
            application/json:
              schema:
                type: object
                required:
                - schemaVersion
                - document
                - unsignedPresentation
                properties:
                  schemaVersion:
                    const: averray.receipt-envelope.v1
                  document:
                    type: object
                    description: Unchanged content-addressed signed receipt.
                  unsignedPresentation:
                    type: object
                    description: Unsigned display aliases; not covered by document.signature.
                additionalProperties: false
        '301':
          description: Alias resolved; fetch the canonical receipt URL.
          headers:
            Location:
              schema:
                type: string
        '404':
          description: Unknown receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /badges:
    get:
      tags:
      - Receipts
      operationId: listBadges
      summary: List recent public badge receipts
      description: 'Cursor-paginated averray.badge-list-item.v1 wrappers, default 50 rows (formerly 100 sessions). Follow nextCursor preserving filters and sort; cursors bind that query plus sessionId/kind. Default order is recent sessions, run before badge. Verify each document alone; unsignedPresentation is not signed. Optional filters read document.verifier.handler, verdict.outcome and settlement.settlementTx. sort=verifiedAt:desc orders by document.timestamps.verifiedAt, never unsigned issuedAt, excluding missing dates. Filtered/sorted results contain run documents only. All filter sets share one base run-row snapshot for 45 seconds, released on expiry; a scan exceeding 10 seconds returns 503 badges_list_scan_timeout and the next request retries. ETag/304 reads reuse it, with public max-age=45. A stale or cross-query cursor requires restarting. All list reads use the badges_list rate-limit bucket (default 60 per minute per client). Unknown query names, including _, return 400. Wrapper schema: https://raw.githubusercontent.com/averray-agent/agent/main/docs/schemas/badge-list-item-v1.json.'
      security: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Receipt rows per page, default 50, maximum 500.
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
      - name: cursor
        in: query
        required: false
        description: Opaque nextCursor from the previous page.
        schema:
          type: string
      - name: handler
        in: query
        required: false
        description: Canonical persisted receipt verifier handler, including brokered human review and witness-configured jobs.
        schema:
          type: string
          enum:
          - benchmark
          - deterministic
          - github_pr
          - human_fallback
          - human_review
          - poster_review
          - witness
      - name: outcome
        in: query
        required: false
        description: Canonical verdict outcome.
        schema:
          type: string
          enum:
          - approved
          - rejected
      - name: settled
        in: query
        required: false
        description: Require a canonical settlement.settlementTx transaction hash.
        schema:
          type: string
          enum:
          - 'true'
      - name: sort
        in: query
        required: false
        description: Descending canonical document.timestamps.verifiedAt; deterministic sessionId/kind tie-break.
        schema:
          type: string
          enum:
          - verifiedAt:desc
      responses:
        '200':
          description: List recent public badge receipts
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - limit
                - nextCursor
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      required:
                      - schemaVersion
                      - document
                      - unsignedPresentation
                      additionalProperties: false
                      properties:
                        schemaVersion:
                          const: averray.badge-list-item.v1
                        document:
                          type: object
                          additionalProperties: true
                        unsignedPresentation:
                          type: object
                          required:
                          - sessionId
                          - kind
                          properties:
                            sessionId:
                              type: string
                              minLength: 1
                            kind:
                              enum:
                              - run
                              - badge
                            issuedAt:
                              type: string
                            policyTags:
                              type: array
                              items:
                                type: string
                          additionalProperties: true
                  limit:
                    type: integer
                  nextCursor:
                    type:
                    - string
                    - 'null'
        '304':
          description: Page unchanged (If-None-Match).
        '400':
          description: Invalid/stale cursor or cursor reused with different filters/sort (invalid_cursor); unsupported query name/value (including cache-busters such as _). Filter errors include details.unknown and details.supported.
        '429':
          description: badges_list request limit exceeded.
        '503':
          description: Receipt-store scan exceeded its 10-second deadline (badges_list_scan_timeout; details.reason receipt_store_read_deadline). Retry the read; the pending snapshot has been discarded.
  /badges/{sessionId}:
    get:
      tags:
      - Receipts
      operationId: getBadge
      summary: Public badge metadata
      description: Public badge metadata.
      security: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Public badge metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Unknown receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /badges/{sessionId}/run:
    get:
      tags:
      - Receipts
      operationId: getRunReceipt
      summary: Public run receipt for a completed work session
      description: Public run receipt for a completed work session.
      security: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Public run receipt for a completed work session.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Unknown receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  responses:
    Forbidden:
      description: The authenticated wallet does not have the required role.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingToken:
              value:
                error: missing_token
                message: Authentication required.
                requestId: f865d489-2400-469a-945a-3c54e74e5b9e
  schemas:
    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