Averray Sessions API

openapi: 3.2.0
info:
  title: Averray HTTP Sessions 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: Sessions
  description: Wallet-scoped work-session history and detail.
paths:
  /sessions:
    get:
      tags:
      - Sessions
      operationId: listWalletSessions
      summary: List sessions for the signed-in wallet
      description: Returns recent work sessions owned by the authenticated wallet, optionally scoped to one job.
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum recent sessions to return. Invalid numeric input falls back to 8.
        schema:
          type: integer
          minimum: 1
          default: 8
      - name: jobId
        in: query
        required: false
        description: Return only sessions for this job.
        schema:
          type: string
      responses:
        '200':
          description: Wallet-scoped session history.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /session:
    get:
      tags:
      - Sessions
      operationId: getWalletSession
      summary: Get one session owned by the signed-in wallet
      description: Fetches one owner-scoped session. Supply its canonical `sessionId`; `id` remains a compatibility alias.
      security:
      - bearerAuth: []
      parameters:
      - name: sessionId
        in: query
        required: false
        description: Canonical session identifier. Required unless the compatibility `id` alias is supplied.
        schema:
          type: string
      - name: id
        in: query
        required: false
        deprecated: true
        description: Compatibility alias for `sessionId`.
        schema:
          type: string
      responses:
        '200':
          description: The requested wallet-owned session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No session exists for the supplied identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionNotFoundResponse'
  /session/state-machine:
    get:
      tags:
      - Sessions
      operationId: getSessionStateMachine
      summary: Read the session lifecycle
      description: Canonical states and transitions for the worker flow.
      security: []
      responses:
        '200':
          description: Read the session lifecycle
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  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
    SessionNotFoundResponse:
      type: object
      required:
      - status
      - sessionId
      properties:
        status:
          type: string
          const: not_found
        sessionId:
          type: string
      additionalProperties: false
    Session:
      type: object
      required:
      - sessionId
      - jobId
      - wallet
      - status
      properties:
        sessionId:
          type: string
        jobId:
          type: string
        wallet:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        status:
          type: string
      additionalProperties: true
  responses:
    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
    Forbidden:
      description: The authenticated wallet does not have the required role.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT