Anteproof Risk API

openapi: 3.2.0
info:
  title: Anteproof Risk 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: Risk
paths:
  /v1/risk:
    get:
      summary: Dependency Risk
      description: 'Dependency risk for a package or repository: the latest open

        maintenance forecasts (commits_90d, release_90d), 90 days of

        commit/release/star activity summarised, the day the entity was last

        velocity-scored (the score itself and its stage label are both

        withheld), the

        plain-language flags those numbers support, and the families'' own

        calibration record — one timestamped answer for an agent choosing a

        dependency. ``q`` is an npm/PyPI/crates.io package name, a GitHub

        owner/repo (or URL), or ``npm:`` / ``pypi:`` / ``crate:`` / ``repo:``

        plus a name. See foresight_api.risk for what each block means and

        how a package is linked to its repository.


        ``view`` (pilot findings, Priority 5): ``full`` (default -- every

        diagnostic field, this endpoint''s historical shape plus ``status`` and

        ``triage``) or ``compact`` (foresight_api.risk_batch.compact_view --

        what was resolved, coverage status, key evidence, forecasts, warnings,

        nothing else). The default stays ``full`` on purpose: entity.html and

        coverage_preview.py already depend on fields (signals, calibration_note,

        repo_link) this endpoint has always returned by default, so making

        compact the default would silently break both rather than opt anyone in.


        ``status`` and ``triage`` are in the DEFAULT answer since #325(a).

        They were not between 2026-09-13 and then: Priority 3/4/5 computed

        them only inside risk_batch, so the two fields the pilot is sold on

        were reachable only from ``?view=compact`` or /v1/risk/batch, while

        both pilot documents'' example URLs are this bare default. Added, never

        substituted -- every field the default carried before is still here,

        so existing consumers read exactly what they read before and gain two.'
      operationId: dependency_risk_v1_risk_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 200
          title: Q
      - name: view
        in: query
        required: false
        schema:
          type: string
          default: full
          title: View
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Dependency Risk V1 Risk Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Risk
  /v1/risk/batch:
    post:
      summary: Risk Batch Endpoint
      description: 'A whole lockfile in one request (pilot findings, Priority 3):

        compact, comparable per-package results in submitted order, with a

        top-level status distinguishing full coverage, partial coverage,

        ambiguity and no coverage (Priority 4) instead of one flat dict a

        caller has to interpret differently for every failure mode. ``view``

        is ``summary`` (default -- foresight_api.risk_batch''s compact fields)

        or ``detail`` (the same full per-package answer /v1/risk gives,

        keyed by query). Ambiguous or unmatched entries never raise for the

        whole batch -- one bad entry becomes one result, not a 4xx for

        packages that would have resolved fine.


        Every result, in both views, carries ``rank``: an integer where 1 is

        the highest ``triage.score`` in this batch, ties broken by submission

        order; null when the entry has no score (not_covered, ambiguous,

        service_error, or insufficient evidence). The list itself stays in

        submission order -- sort by ``rank`` to get the riskiest first.'
      operationId: risk_batch_endpoint_v1_risk_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Risk Batch Endpoint V1 Risk Batch Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Risk
  /v1/risk/top:
    get:
      summary: Top Risk
      description: 'The digest''s "Most at risk this week" table as JSON: the ``limit``

        repositories with the lowest open maintenance forecasts (commits_90d,

        release_90d) among source repositories of packages with at least

        ``min_dependents`` dependent repositories (ecosyste.ms), one row per

        repository with both family probabilities, ranked by the lower one.

        Public and read-only; see foresight_api.risk.top_at_risk for the

        selection and the honest empty states (``open_questions`` says

        whether anything is open at all).'
      operationId: top_risk_v1_risk_top_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
          title: Limit
      - name: min_dependents
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 1000
          title: Min Dependents
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Top Risk V1 Risk Top Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Risk
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
    RiskBatchRequest:
      properties:
        packages:
          items:
            type: string
          type: array
          maxItems: 25
          minItems: 1
          title: Packages
        view:
          type: string
          title: View
          default: summary
      type: object
      required:
      - packages
      title: RiskBatchRequest
  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.'