Anteproof Calibration API

openapi: 3.2.0
info:
  title: Anteproof Calibration API
  description: 'Read-only access to the Anteproof forecast archive: live forecasts, question detail, and the full calibration/launch-gate audit trail. Anteproof is a product of Recoilix LLC.'
  version: 0.1.0
tags:
- name: Calibration
paths:
  /v1/calibration:
    get:
      summary: Calibration
      description: 'The transparency record: latest calibration snapshot per domain

        plus EVERY launch-gate evaluation ever run, verdicts included —

        failing runs are part of the audit trail, not something to hide.


        A run whose report names a family in

        `calibration.UNTRUSTED_RESOLUTION_FAMILIES` is published as a run and

        withheld as a measurement. The row keeps when it ran, its domain,

        family, as-of date, horizon, forecaster version and verdict; every

        statistic in its `report` is JSON `null` (never 0, never an omitted

        key) and the row carries a `withheld` block with

        `reason: "resolutions_untrusted"` saying why. `reasons` goes with

        them, as a whole list, because those strings quote the same figures in

        prose. `withheld` is `null` on every row still published, and rows for

        trusted families — the `rollup_threshold` news-tone record included —

        are returned exactly as stored.


        That the runs stay visible is deliberate and is the honest half of

        the story: we ran our own backtest, found the GH Archive series under

        those resolutions had collapsed, and withdrew the numbers. Deleting

        the rows would hide the withdrawal too.


        Withheld per ROW, not per latest row: `proof._gate_withheld` reads

        only the newest evaluation (`ORDER BY id DESC LIMIT 1`), and the

        withdrawn runs are history. This matches /v1/risk, /v1/proof and the

        calibration page exactly — one endpoint must not publish a number the

        next one withholds.'
      operationId: calibration_v1_calibration_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Calibration V1 Calibration Get
      tags:
      - Calibration
  /v1/calibration/families:
    get:
      summary: Calibration By Family
      description: 'The calibration page''s data: the same resolved-forecast pool the

        launch gate judges, broken down by question family, plus the live

        track the gate does not judge yet. Scope follows the gate exactly. The pastcast track is the current

        question-generation scheme and the forecaster version named by the

        most recent gate evaluation — older regimes are retired, and mixing

        them was measured to flatter the numbers (see

        foresight_backtest.report._resolved_pastcasts). The live track is

        every real-time forecast that has resolved, all versions, because a

        reader deserves the whole real-time record, not a curated slice. One row per question: the latest forecast, which is what resolution

        scored against. Horizon is the REAL horizon the gate scopes on — resolution date

        minus the as-of date (a live forecast''s issue date) — bucketed, with

        every bucket''s row count returned so the page can offer only the

        scopes that exist. The default scope is the gate verdict''s own

        horizon (its report''s `horizon_days`, bucketed): since the 30-day

        experiment the archive holds pastcasts at more than one horizon and

        pooling them was measured to flatter the headline (BSS 0.155 pooled

        against 0.107 at the gate''s 7 days). `horizon=all` pools on purpose;

        a verdict that names no horizon (older reports) scopes nothing. The verdict follows the same scope. `regime.gate` is the latest

        verdict that judged THIS horizon, or null with `regime.gate_scope`

        saying in words that no gate covers it — never a fallback to another

        horizon''s verdict, because a passing 7-day verdict served beside the

        90-day maintenance families reads as those families having passed a

        gate they have not. `regime.latest_gate` still carries the newest

        verdict overall, stamped with its own `domain` and `horizon_days`, so

        the distinction survives outside the browser (the MCP tool has no

        page, no card and no selector). Both verdict blocks are under the withheld contract, through

        `calibration.public_gate_row` — the same helper /v1/calibration''s

        `gate_history` uses, not a second copy of the rule. A verdict scoped

        to a withheld family keeps its identity and its recorded `passes`,

        every statistic in its `report` is `null`, and it carries a

        `withheld` block; `withheld` is `null` on every verdict still

        published. This block used to be the row as stored, `report` blob and

        all, and it read as harmless only while the newest row happened to be

        the trusted news-tone run: the first gate row scoped to a withheld

        family — which is what a backtest over the maintenance families

        creates — would have published that family''s `n` and Brier skill

        here, from a route whose family table withholds exactly those numbers

        three keys further down. Every family resolved off a GH Archive activity series is WITHHELD,

        unconditionally: the windowed maintenance families (`commits_90d`,

        `release_90d`) and the legacy daily-threshold families that read the

        same three series (`commits_hourly`, `release_published`,

        `stars_hourly` — keyed by their metric because they carry no

        provenance family). Every question in that pool was resolved by

        counting a GH Archive series whose capture collapsed, so the outcomes

        those forecasts were scored against are themselves unreliable and no

        score over the pool is sound — at any horizon, over any window, however

        healthy the series looks now. Their `n` and every statistic beside it

        are JSON `null` (never 0, never omitted) and the family carries a

        `withheld` block with `reason: "resolutions_untrusted"` saying so;

        `withheld` is `null` on everything still published. Their rows are not

        folded into a track total either, and a track left with nothing to

        score goes null rather than reporting n=0. This matches /v1/risk and

        /v1/proof exactly: one endpoint must not withhold a number the next

        one publishes. It does not end when the source looks healthy again.'
      operationId: calibration_by_family_v1_calibration_families_get
      parameters:
      - name: horizon
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Horizon bucket to scope to: 7 (up to 7 days), 30, 90 or long (over 90); ''all'' for every horizon. Omit for the horizon the latest gate verdict scopes on. `regime.gate` is the verdict for the horizon asked for, or null when none was run on it; `regime.latest_gate` is the newest verdict overall, whatever its horizon.'
          title: Horizon
        description: 'Horizon bucket to scope to: 7 (up to 7 days), 30, 90 or long (over 90); ''all'' for every horizon. Omit for the horizon the latest gate verdict scopes on. `regime.gate` is the verdict for the horizon asked for, or null when none was run on it; `regime.latest_gate` is the newest verdict overall, whatever its horizon.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Calibration By Family V1 Calibration Families Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Calibration
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    clerkSessionBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A Clerk session token, sent as `Authorization: Bearer <jwt>`. The signature (RS256, against the configured Clerk JWKS) and the expiry are verified; the issuer and the authorized party are also checked where they are configured. An operation marked with this scheme refuses a request that does not carry a valid session token. An Anteproof API key is not accepted in its place.'
    anteproofApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'An Anteproof API key (`ap_…`), created at https://anteproof.com/account. On the public operations in this document — the ones that list no security requirement — it may be sent either as `X-API-Key: ap_…` or as `Authorization: Bearer ap_…`. It is OPTIONAL on those: a request without it is served just the same, and a request with a live key is counted against the account''s monthly allowance (the reply then carries X-Api-Calls-Used, X-Api-Calls-Limit and X-Api-Calls-Reset). It is not a session credential: an operation marked `clerkSessionBearer` refuses it with 401, live key or not. An `ap_…` key that is invalid or revoked is refused with 401 on any operation in this document; otherwise the key is optional. Because no operation requires one, no operation in this document lists this scheme. The MCP endpoint at /mcp, which this document does not describe, requires a credential — an API key or an OAuth sign-in — for every call except discovery: a POST whose JSON-RPC messages are all `initialize`, `notifications/initialized`, `ping` or `tools/list` is served without one.'
    stripeWebhookSignature:
      type: apiKey
      in: header
      name: Stripe-Signature
      description: 'Stripe''s webhook signature: `t=<unix>,v1=<hex hmac-sha256 of "<t>.<body>">`, checked against this endpoint''s signing secret with a five-minute tolerance on `t`. A request whose signature does not verify is refused with 401. This operation receives Stripe''s callbacks.'