openapi: 3.0.0
paths:
  /v1/oracle/scu:
    get:
      operationId: OraclePublicController_getScu
      summary: Get current SCU value and breakdown
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScuResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/models:
    get:
      operationId: OraclePublicController_getModels
      summary: List all basket models
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/model/{key}:
    get:
      operationId: OraclePublicController_getModel
      summary: Get single model price by key
      parameters:
        - name: key
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/tiers:
    get:
      operationId: OraclePublicController_getTiers
      summary: Get tier breakdown with weights and contributions
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TiersResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/basket:
    get:
      operationId: OraclePublicController_getBasket
      summary: Get full basket composition
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/baseline:
    get:
      operationId: OraclePublicController_getBaseline
      summary: Inception SCU snapshot for Efficiency Index denominator
      parameters: []
      responses:
        '200':
          description: Inception SCU snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaselineResponseDto'
        '204':
          description: No confirmed revision exists yet
      tags:
        - Oracle Public
  /v1/oracle/history:
    get:
      operationId: OraclePublicController_getHistory
      summary: Get SCU time series for charting
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OracleHistoryResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/reconstitutions:
    get:
      operationId: OraclePublicController_getReconstitutions
      summary: Get reconstitution event log
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconstitutionsResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/reconstitutions/export:
    get:
      operationId: OraclePublicController_exportReconstitutions
      summary: Export reconstitution history as markdown
      parameters: []
      responses:
        '200':
          description: Reconstitution log rendered as a downloadable markdown attachment
          content:
            text/markdown:
              schema:
                type: string
      tags:
        - Oracle Public
  /v1/oracle/prices/history:
    get:
      operationId: OraclePublicController_getPriceHistory
      summary: Get per-model price history
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceHistoryResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/latest:
    get:
      operationId: OraclePublicController_getLatest
      summary: Latest confirmed revision summary
      description: >-
        Lightweight endpoint returning the latest CONFIRMED revision's version,
        publish timestamp, tx hash, confirmation time, SCU in USD, and basket
        size. No full basket payload.
      parameters: []
      responses:
        '200':
          description: Latest revision summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRevisionSummaryResponseDto'
        '204':
          description: No confirmed revision exists yet
      tags:
        - Oracle Public
  /v1/oracle/health:
    get:
      operationId: OraclePublicController_getHealth
      summary: Oracle health probe
      description: >-
        Latest confirmed revision version and timestamp. Returns nulls when no
        revisions have been confirmed yet.
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OracleHealthResponseDto'
      tags:
        - Oracle Public
  /v1/oracle/stats:
    get:
      operationId: OraclePublicController_getStats
      summary: Public aggregate protocol stats
      parameters: []
      responses:
        '200':
          description: Aggregate protocol metrics
      tags:
        - Oracle Public
  /v1/oracle/activity:
    get:
      operationId: OraclePublicController_getActivityFeed
      summary: Live activity feed
      parameters: []
      responses:
        '200':
          description: Paginated activity events
      tags:
        - Oracle Public
  /v1/oracle/pricing:
    get:
      operationId: OraclePublicController_getPricing
      summary: Per-model pricing in $COMPUTE and USD
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Oracle Public
info:
  title: Compute Finance Public API
  description: >-
    Read-only public endpoints for the Compute Price Index (CPI). No
    authentication. JSON responses. Stable schemas. Covers the Standard Compute
    Unit (SCU), basket composition, model prices, historical snapshots, and
    aggregate protocol statistics. For the full internal spec see
    /docs/openapi.yaml.
  version: '1.0'
  contact:
    name: Compute Finance
    url: https://compute.finance
    email: hello@compute.finance
  license:
    name: MIT
    url: https://opensource.org/license/mit
tags:
  - name: Oracle Public
    description: Pricing, SCU, basket, history — /v1/oracle endpoints
servers:
  - url: https://api.compute.finance
    description: Production
components:
  schemas:
    ScuResponseDto:
      type: object
      properties:
        scuUsd:
          type: number
        breakdown:
          type: object
          properties:
            frontier:
              type: number
            standard:
              type: number
            lightweight:
              type: number
          selfRequired: true
        referenceWorkload:
          type: object
          properties:
            inputTokens:
              type: number
            outputTokens:
              type: number
          selfRequired: true
        methodology:
          type: string
        updatedAt:
          type: string
      required:
        - scuUsd
        - breakdown
        - referenceWorkload
        - methodology
        - updatedAt
    ModelsResponseDto:
      type: object
      properties:
        models:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              displayName:
                type: string
              provider:
                type: object
                properties:
                  key:
                    type: string
                  name:
                    type: string
                required:
                  - key
                  - name
              tier:
                type: string
              integrated:
                description: >-
                  Whether this model is routable through /v1/chat/completions.
                  Basket-only models are priced but not callable.
                type: boolean
              ctPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              usdPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              markedUpCtPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              markedUpUsdPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              oracleKeyPrefix:
                type: string
              releasedAt:
                type: string
                format: date-time
                nullable: true
            required:
              - id
              - displayName
              - provider
              - tier
              - integrated
              - ctPricePerMillion
              - usdPricePerMillion
              - markedUpCtPricePerMillion
              - markedUpUsdPricePerMillion
              - oracleKeyPrefix
              - releasedAt
      required:
        - models
    ModelResponseDto:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        provider:
          type: object
          properties:
            key:
              type: string
            name:
              type: string
          selfRequired: true
        tier:
          type: string
        integrated:
          type: boolean
        ctPricePerMillion:
          type: object
          properties:
            input:
              type: number
            output:
              type: number
          selfRequired: true
        usdPricePerMillion:
          type: object
          properties:
            input:
              type: number
            output:
              type: number
          selfRequired: true
        markedUpCtPricePerMillion:
          type: object
          properties:
            input:
              type: number
            output:
              type: number
          selfRequired: true
        markedUpUsdPricePerMillion:
          type: object
          properties:
            input:
              type: number
            output:
              type: number
          selfRequired: true
      required:
        - id
        - displayName
        - provider
        - tier
        - integrated
        - ctPricePerMillion
        - usdPricePerMillion
        - markedUpCtPricePerMillion
        - markedUpUsdPricePerMillion
    TiersResponseDto:
      type: object
      properties:
        tiers:
          type: object
          additionalProperties:
            type: object
            properties:
              weight:
                type: number
              models:
                type: number
              avgCostUsd:
                type: number
              contribution:
                type: number
            required:
              - weight
              - models
              - avgCostUsd
              - contribution
          selfRequired: true
        scuUsd:
          type: number
      required:
        - tiers
        - scuUsd
    BasketResponseDto:
      type: object
      properties:
        models:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              displayName:
                type: string
              provider:
                type: object
                properties:
                  key:
                    type: string
                  name:
                    type: string
                required:
                  - key
                  - name
              tier:
                type: string
              integrated:
                description: >-
                  Whether this model is routable through /v1/chat/completions.
                  Basket-only models are priced but not callable.
                type: boolean
              ctPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              usdPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              markedUpCtPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              markedUpUsdPricePerMillion:
                type: object
                properties:
                  input:
                    type: number
                  output:
                    type: number
                required:
                  - input
                  - output
              oracleKeyPrefix:
                type: string
              releasedAt:
                type: string
                format: date-time
                nullable: true
            required:
              - id
              - displayName
              - provider
              - tier
              - integrated
              - ctPricePerMillion
              - usdPricePerMillion
              - markedUpCtPricePerMillion
              - markedUpUsdPricePerMillion
              - oracleKeyPrefix
              - releasedAt
        scu:
          type: object
          properties:
            frontier:
              type: number
            standard:
              type: number
            lightweight:
              type: number
            total:
              type: number
          selfRequired: true
        scuUsd:
          type: number
        routingFeeRate:
          type: number
        revisionVersion:
          type: number
          nullable: true
        basketVersion:
          type: number
          nullable: true
        lastUpdated:
          type: string
      required:
        - models
        - scu
        - scuUsd
        - routingFeeRate
        - revisionVersion
        - basketVersion
        - lastUpdated
    BaselineResponseDto:
      type: object
      properties:
        date:
          type: string
        scu:
          type: number
        frontier:
          type: number
        standard:
          type: number
        lightweight:
          type: number
      required:
        - date
        - scu
        - frontier
        - standard
        - lightweight
    OracleHistoryResponseDto:
      type: object
      properties:
        range:
          type: string
        from:
          type: string
        to:
          type: string
        count:
          type: number
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              scu:
                type: number
              frontier:
                type: number
              standard:
                type: number
              lightweight:
                type: number
              basketVersion:
                type: number
            required:
              - date
              - scu
              - frontier
              - standard
              - lightweight
              - basketVersion
      required:
        - range
        - from
        - to
        - count
        - data
    ReconstitutionsResponseDto:
      type: object
      properties:
        entries:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              revisionVersion:
                type: integer
              previousVersion:
                type: integer
                nullable: true
              publishedAt:
                type: string
              summary:
                type: string
              scuBefore:
                type: number
                nullable: true
              scuAfter:
                type: number
              changes:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    modelKey:
                      type: string
                    tier:
                      type: string
                    description:
                      type: string
                    before:
                      type: object
                      additionalProperties: {}
                    after:
                      type: object
                      additionalProperties: {}
                  required:
                    - type
                    - description
              txHash:
                type: string
                nullable: true
            required:
              - id
              - revisionVersion
              - previousVersion
              - publishedAt
              - summary
              - scuBefore
              - scuAfter
              - changes
              - txHash
      required:
        - entries
    PriceHistoryResponseDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              modelId:
                type: string
              displayName:
                type: string
              provider:
                type: string
              tier:
                type: string
              inputPrice:
                type: number
              outputPrice:
                type: number
              basketVersion:
                type: number
            required:
              - date
              - modelId
              - displayName
              - provider
              - tier
              - inputPrice
              - outputPrice
              - basketVersion
      required:
        - data
    LatestRevisionSummaryResponseDto:
      type: object
      properties:
        revisionVersion:
          type: integer
          minimum: 0
          exclusiveMinimum: false
        publishedAt:
          type: string
        confirmedAt:
          type: string
          nullable: true
        scuUsd:
          type: number
        basketSize:
          type: integer
          minimum: 0
          exclusiveMinimum: false
        tierWeightsBps:
          type: array
          items:
            oneOf:
              - type: integer
              - type: integer
              - type: integer
        workload:
          type: object
          properties:
            inputTokens:
              type: integer
              minimum: 0
              exclusiveMinimum: false
            outputTokens:
              type: integer
              minimum: 0
              exclusiveMinimum: false
          selfRequired: true
      required:
        - revisionVersion
        - publishedAt
        - confirmedAt
        - scuUsd
        - basketSize
        - tierWeightsBps
        - workload
    OracleHealthResponseDto:
      type: object
      properties:
        latestRevisionVersion:
          type: integer
          nullable: true
        latestRevisionConfirmedAt:
          type: string
          format: date-time
          nullable: true
        lastSyncAt:
          type: string
          format: date-time
          nullable: true
        stale:
          type: boolean
      required:
        - latestRevisionVersion
        - latestRevisionConfirmedAt
        - lastSyncAt
        - stale
externalDocs:
  description: Methodology and guides
  url: https://docs.compute.finance