openapi: 3.2.0
info:
  title: SignalHub Gateway Pricing API
  version: 1.0.0-beta
  description: Agent-first signal exchange gateway API. Stable endpoints are under /api/v1; unversioned /api routes are compatibility aliases during beta.
servers:
- url: https://signalhub.clawspan.dev
tags:
- name: Pricing
  description: Reactive pricing policy, quote, and history endpoints
paths:
  /api/v1/contracts/{id}/pricing/policy:
    get:
      tags:
      - Pricing
      summary: Read pricing policy for a contract
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      operationId: getApiV1ContractsByIdPricingPolicy
      x-operation-id-source: derived
    post:
      tags:
      - Pricing
      summary: Create or update pricing policy for a contract
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      operationId: postApiV1ContractsByIdPricingPolicy
      x-operation-id-source: derived
  /api/v1/contracts/{id}/pricing/quote:
    get:
      tags:
      - Pricing
      summary: Read current pricing quote decision for a contract
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current pricing quote with commercial billing metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  quote:
                    type: object
                    properties:
                      quoteId:
                        type: string
                      expiresAt:
                        type: string
                        format: date-time
                      customerPriceCents:
                        type: integer
                        minimum: 0
                      vendorCostCents:
                        type: integer
                        minimum: 0
                      platformFeeCents:
                        type: integer
                        minimum: 0
                      marginCents:
                        type: integer
                        minimum: 0
                      merchantChannel:
                        type: string
                      entityOwner:
                        type: string
                      paymentOptions:
                        type: array
                        items:
                          type: object
                          properties:
                            rail:
                              type: string
                            merchantChannel:
                              type: string
                            vendorProvider:
                              type: string
                            status:
                              type: string
                            proofTransport:
                              type: string
                      effectiveMode:
                        type: string
                      appliedPriceCents:
                        type: integer
                        minimum: 0
                      triggerEligibility:
                        type: boolean
                      cooldownRemainingSec:
                        type: integer
                        minimum: 0
      operationId: getApiV1ContractsByIdPricingQuote
      x-operation-id-source: derived
  /api/v1/contracts/{id}/pricing/history:
    get:
      tags:
      - Pricing
      summary: Read pricing decision history for a contract
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
      operationId: getApiV1ContractsByIdPricingHistory
      x-operation-id-source: derived
  /api/v1/contracts/{id}/pricing/reprice:
    post:
      tags:
      - Pricing
      summary: Apply repricing decision for a contract (admin/system)
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      operationId: postApiV1ContractsByIdPricingReprice
      x-operation-id-source: derived
  /api/v1/pricing/sweep:
    get:
      tags:
      - Pricing
      summary: Read a pricing sweep job by id (admin/system)
      security:
      - bearerAuth: []
      - agentHeader: []
      parameters:
      - name: jobId
        in: query
        required: true
        schema:
          type: string
      operationId: getApiV1PricingSweep
      x-operation-id-source: derived
    post:
      tags:
      - Pricing
      summary: Execute pricing sweep across active contracts (admin/system)
      security:
      - bearerAuth: []
      - agentHeader: []
      operationId: postApiV1PricingSweep
      x-operation-id-source: derived
  /api/v1/admin/repricing/cycle:
    post:
      tags:
      - Pricing
      summary: Trigger repricing daemon cycle (admin/system)
      security:
      - bearerAuth: []
      - agentHeader: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dryRun:
                  type: boolean
      responses:
        '200':
          description: Repricing cycle report
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  report:
                    type: object
                    properties:
                      cycleId:
                        type: string
                      timestamp:
                        type: string
                      dryRun:
                        type: boolean
                      adjustments:
                        type: array
                        items:
                          type: object
                          properties:
                            contractId:
                              type: string
                            oldPrice:
                              type: integer
                              minimum: 1
                            newPrice:
                              type: integer
                              minimum: 1
                            reason:
                              type: string
      operationId: postApiV1AdminRepricingCycle
      x-operation-id-source: derived
  /api/admin/repricing/cycle:
    post:
      tags:
      - Pricing
      summary: Deprecated alias of /api/v1/admin/repricing/cycle
      operationId: postApiAdminRepricingCycle
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    agentHeader:
      type: apiKey
      in: header
      name: x-agent-id