openapi: 3.2.0
info:
  title: tokenusage.dev public data Resets 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: Resets
paths:
  /api/resets:
    description: At most the 50 newest visible announcements recorded from @thsottiaux, newest postedAt first; not a complete history. A post is not proof that any account's limit was reset. Use GET or HEAD without credentials or custom request headers. Poll no faster than every 15 seconds. Unsupported methods return the documented 405 error.
    get:
      operationId: getResetAnnouncements
      summary: Read recorded Codex reset announcements
      responses:
        '200':
          $ref: '#/components/responses/ResetJson'
        '405':
          $ref: '#/components/responses/ResetMethodNotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Resets
    head:
      operationId: headResetAnnouncements
      summary: Read reset JSON response headers
      responses:
        '200':
          $ref: '#/components/responses/ResetHead'
        '405':
          $ref: '#/components/responses/HeadError'
        '500':
          $ref: '#/components/responses/HeadError'
      tags:
      - Resets
components:
  schemas:
    ResetPublicItem:
      type: object
      additionalProperties: true
      required:
      - postId
      - url
      - postedAt
      - detectedAt
      - resetType
      properties:
        postId:
          type: string
        url:
          type: string
          format: uri
          description: Source-post URL.
        postedAt:
          type: string
          format: date-time
          description: When the source post was published.
        detectedAt:
          type: string
          format: date-time
          description: When the monitor recorded the announcement.
        resetType:
          type:
          - string
          - 'null'
          enum:
          - automatic
          - banked
          - both
          - null
          description: 'Monitor classification: automatic is a direct usage-limit reset with no saved reset; banked is a grant saved for eligible users to apply later and does not itself refill limits; both includes both types. Null means recorded before reset types were recorded. Not proof that any account''s limit was reset.'
    ResetsResponse:
      type: object
      additionalProperties: true
      required:
      - source
      - generatedAt
      - lastPolledAt
      - resets
      properties:
        source:
          type: string
          const: https://tokenusage.dev/resets
          description: Fixed reset credit URL.
        generatedAt:
          type: string
          format: date-time
          description: Response generation time, not data modification time.
        lastPolledAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Latest successful timeline fetch and persistence checkpoint, including checks with no new posts; null before the first or when a legacy record lacks it. Not a classification or delivery heartbeat.
        resets:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/ResetPublicItem'
    Error:
      type: object
      additionalProperties: true
      required:
      - error
      - message
      properties:
        error:
          type: string
        message:
          type: string
  responses:
    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'
    ResetJson:
      description: Recorded announcements. Additional response fields are the site's own interface unless documented as stable.
      headers:
        Cache-Control:
          $ref: '#/components/headers/ResetCache'
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/PublicCors'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResetsResponse'
    ResetHead:
      description: The selected reset path's GET headers, with no transmitted body. Content-Type is application/json for /api/resets and application/atom+xml; charset=utf-8 for /api/resets.atom.
      headers:
        Cache-Control:
          $ref: '#/components/headers/ResetCache'
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/PublicCors'
        X-Robots-Tag:
          $ref: '#/components/headers/Noindex'
    ResetMethodNotAllowed:
      description: Unsupported method on either reset path. 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 or HEAD
    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
  headers:
    Noindex:
      schema:
        type: string
        const: noindex
    PublicCors:
      description: Successful public reads only; no credentialed CORS.
      schema:
        type: string
        const: '*'
    ResetCache:
      schema:
        type: string
        const: public, max-age=0, s-maxage=15
    NoStore:
      schema:
        type: string
        const: no-store
externalDocs:
  description: Fields, caching and reuse conditions
  url: https://tokenusage.dev/developers