openapi: 3.2.0
info:
  title: tokenusage.dev public data Nerfwatch API
  version: 1.0.0
  description: 'Read-only reset announcements and Nerf Watch scores. No key. Public display requires Data: tokenusage.dev linked to https://tokenusage.dev/resets for resets or https://tokenusage.dev/nerfwatch for scores on the same screen or in the same message. Personal use needs no visible credit. Relays must pass on the credit URL and condition. A lower score on this suite is not proof that a provider changed a model. Response fields may be added.'
  termsOfService: https://tokenusage.dev/terms
  contact:
    name: tokenusage.dev
    email: support@tokenusage.dev
    url: https://tokenusage.dev/contact
servers:
- url: https://tokenusage.dev
security: []
tags:
- name: Nerfwatch
paths:
  /api/nerfwatch:
    description: Each model's latest score, previous run, changes, baseline and history, ordered by provider, name and model id. Missing days are missing, not zero. Comparisons use one suite version. A lower score is a lower score on this suite, not proof that a provider changed a model. Use GET or HEAD without credentials or custom request headers. Poll no faster than every 5 minutes. evidenceAvailable and private evidence endpoints are outside this stable reuse contract. Unsupported methods return the documented 405 error.
    get:
      operationId: getNerfWatchScores
      summary: Read Nerf Watch scores and history
      responses:
        '200':
          $ref: '#/components/responses/NerfwatchJson'
        '405':
          $ref: '#/components/responses/NerfwatchMethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Nerfwatch
    head:
      operationId: headNerfWatchScores
      summary: Read Nerf Watch response headers
      responses:
        '200':
          $ref: '#/components/responses/NerfwatchHead'
        '405':
          $ref: '#/components/responses/HeadError'
        '500':
          $ref: '#/components/responses/HeadError'
      tags:
      - Nerfwatch
components:
  schemas:
    NerfwatchModel:
      type: object
      additionalProperties: true
      required:
      - model
      - name
      - provider
      - latest
      - previous
      - change
      - baseline
      - baselineRuns
      - changeVsBaseline
      - trend
      - history
      properties:
        model:
          type: string
        name:
          type: string
        provider:
          type: string
        latest:
          description: Newest run, or null.
          anyOf:
          - $ref: '#/components/schemas/NerfwatchPoint'
          - type: 'null'
        previous:
          description: Run before the latest, whatever its day, or null.
          anyOf:
          - $ref: '#/components/schemas/NerfwatchPoint'
          - type: 'null'
        change:
          type:
          - number
          - 'null'
          minimum: -100
          maximum: 100
          description: Latest minus previous, in points, rounded to two decimals; null without a previous run on the same suite version.
        baseline:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
          description: Mean of same-suite scores in the baseline window, rounded to two decimals; null with too few runs.
        baselineRuns:
          type: integer
          minimum: 0
          description: Number of same-suite runs in the baseline window, even when too few for a baseline.
        changeVsBaseline:
          type:
          - number
          - 'null'
          minimum: -100
          maximum: 100
          description: Latest minus baseline, in points, rounded to two decimals; null without a baseline.
        trend:
          type:
          - string
          - 'null'
          enum:
          - down
          - flat
          - up
          - null
          description: Direction against the baseline using flatPoints; null without a baseline.
        history:
          type: array
          description: Oldest first. Days without a run are missing, not zero.
          items:
            $ref: '#/components/schemas/NerfwatchPoint'
    Error:
      type: object
      additionalProperties: true
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
    NerfwatchPoint:
      type: object
      additionalProperties: true
      required:
      - day
      - score
      - suiteVersion
      properties:
        day:
          type: string
          format: date
          description: UTC day.
        score:
          type: number
          minimum: 0
          maximum: 100
          description: Percent score on this suite, rounded to two decimals.
        suiteVersion:
          type: string
          description: Comparisons are made only within one suite version.
    NerfwatchResponse:
      type: object
      additionalProperties: true
      required:
      - generatedAt
      - dataUpdatedAt
      - historyDays
      - baselineDays
      - minBaselineRuns
      - flatPoints
      - models
      properties:
        generatedAt:
          type: string
          format: date-time
          description: Response generation time.
        dataUpdatedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the newest retained run was stored; null without runs.
        historyDays:
          type: integer
          minimum: 1
          examples:
          - 366
          description: History retention bound per model.
        baselineDays:
          type: integer
          minimum: 1
          examples:
          - 7
          description: UTC-day window before the latest run used for its baseline.
        minBaselineRuns:
          type: integer
          minimum: 1
          examples:
          - 3
          description: Minimum same-suite runs needed for a baseline.
        flatPoints:
          type: number
          minimum: 0
          examples:
          - 2
          description: Absolute change versus baseline at or below this value is flat.
        models:
          type: array
          description: Ordered by provider, name and model id; empty before the first run.
          items:
            $ref: '#/components/schemas/NerfwatchModel'
  responses:
    NerfwatchMethodNotAllowed:
      description: Unsupported method. The existing method message remains GET. No CORS headers are sent.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: method_not_allowed
            message: GET
    NerfwatchHead:
      description: GET headers, with no transmitted body.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NerfwatchCache'
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/PublicCors'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
    HeadError:
      description: Error headers with no transmitted body and no CORS headers.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
    InternalError:
      description: The read failed. No CORS headers are sent.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal
            message: something went wrong on our side
    NerfwatchJson:
      description: Public scores and metadata. Additional response fields are the site's own interface unless documented as stable.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NerfwatchCache'
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/PublicCors'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NerfwatchResponse'
  headers:
    Noindex:
      schema:
        type: string
        const: noindex
    PublicCors:
      description: Successful public reads only; no credentialed CORS.
      schema:
        type: string
        const: '*'
    NerfwatchCache:
      schema:
        type: string
        const: public, max-age=60, s-maxage=300
    NoStore:
      schema:
        type: string
        const: no-store
externalDocs:
  description: Fields, caching and reuse conditions
  url: https://tokenusage.dev/developers