Attestari Health API

openapi: 3.2.0
info:
  title: Attestari lookup Health API
  description: 'The lookup API over the cumulative index of every decided run. Read-only: GET only, and nothing is written anywhere. GET /v1/verdict/{ecosystem}/{name} the newest examined version of that package, and every other examined version

    GET /v1/verdict/{ecosystem}/{name}/{version} grade, decision, methodology, provenance, findings, capabilities, anchors; every examined

    version; the older decisions of this version, which `?methodology=`

    (the latest decision under that methodology) or `?run=` (that run''s

    decision) retrieve

    GET /v1/manifest/{ecosystem}/{name}/{version} the attested manifest: manifest hash and per-tool digests (`?methodology=` and

    `?run=` too); when the index holds a `manifest_changed` event for the

    decision, the manifest hash of the previous examined version and that

    version (`previous_manifest_sha256`, `changed_since`). An event, not a

    finding: no grade depends on it

    GET /v1/health the runs served, the newest run and methodology, row counts


    Every lookup (/v1/verdict, /v1/manifest) carries a key (`Authorization: Bearer `); /v1/health and the spec do not. A key is made in the web app

    (app.attestari.ai, API keys & MCP) and is accepted here while it is not revoked and its organization''s plan includes

    lookups (attestari_api/keys.py). A verdict asked for without one is answered with the public summary only

    (`VerdictSummary`: package, version, grade, date, methodology version and document hash, finding count, highest

    severity, class names), the same the public result page shows; findings with file:line, the capability inventory,

    provenance and version history are the full report, which needs a key (price book revision 3). A manifest is the full

    report too: without a key it is a 401. A key that is not accepted is a 401, never a summary; a key whose organization

    has no plan that includes lookups is a 403. A keyed call answered 200 is one lookup, counted for its key (also when the answer to a conditional request is "not

    modified"); 401, 403, 404, 429 and 5xx are not counted. Every counted answer says how far the organization is into its

    month: `Attestari-Lookups-Used` and `Attestari-Lookups-Included` (the calendar month in UTC, every key of the

    organization together), and `Attestari-Lookups-Warning: 100` or `150` once that percentage of the allowance is used. Once the plan is paid, lookups past the allowance are answered like any other: nothing is cut off. While the

    organization''s subscription is in its trial the allowance is a cap (attestari-engineers@2026-09-30): a lookup past

    it is 403 `trial_allowance_reached`, not counted, until the trial ends. The attested manifest (/v1/manifest) is the Platform tier''s (price book revision 3, line 2); no plan sold today

    includes it. A key of any other plan is 403 `plan_without_manifest`, not counted. Rate limits (attestari-engineers@2026-09-30): a keyed call is limited per key, at the rate the key''s plan sets, which

    the accounts database answers with the key (Small business 120 a minute, Enterprise 600, API Developer 60); a call

    without a key, and a call whose key is not accepted, is limited per client address (60 a minute). A key this service

    does not remember from the last sixty seconds is charged to the client address before the accounts database is asked

    about it, and the token is given back when the key is accepted; a call that comes from an address with no tokens left

    is a 429 before its key is checked. /v1/health and the spec are limited per address whatever is sent, and so is a

    call shaped like a lookup that matches no route. An IPv6 client is counted by its /64. First-party callers (attestari_api/identity.py): the web app and the accounts service''s monitoring job send a Google

    identity token of their own service account in the same header. Such a call is answered as a keyed call is (the full

    report, the manifest), is counted for nobody, and is limited per caller (3,000 a minute).'
  version: '1'
tags:
- name: Health
paths:
  /v1/health:
    get:
      summary: the run served
      operationId: health_v1_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
      tags:
      - Health
components:
  schemas:
    LastPromotion:
      properties:
        run_id:
          type: string
          title: Run Id
          description: the run the last promotion served
        promoted_by:
          anyOf:
          - type: string
            enum:
            - auto
            - pre-gate
            - engineers
          - type: 'null'
          title: Promoted By
          description: auto, engineers or pre-gate, as in `runs`; never a person
        promoted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Promoted At
        methodology_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Methodology Version
      type: object
      required:
      - run_id
      title: LastPromotion
    RunRef:
      properties:
        run_id:
          type: string
          title: Run Id
        methodology_version:
          type: string
          title: Methodology Version
        decided_at:
          type: string
          title: Decided At
        promoted_by:
          anyOf:
          - type: string
            enum:
            - auto
            - pre-gate
            - engineers
          - type: 'null'
          title: Promoted By
          description: 'who promoted the run: auto (the promotion gate), engineers (the Attestari engineers, by hand), or pre-gate (indexed before the gate existed); never a person'
        promoted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Promoted At
      type: object
      required:
      - run_id
      - methodology_version
      - decided_at
      title: RunRef
    Health:
      properties:
        status:
          type: string
          const: ok
          title: Status
        run_id:
          type: string
          title: Run Id
          description: the newest served run in the index
        methodology_version:
          type: string
          title: Methodology Version
          description: the methodology the newest run was decided under
        methodology_sha256:
          type: string
          title: Methodology Sha256
        methodology_url:
          type: string
          title: Methodology Url
        rows:
          type: integer
          title: Rows
          description: decision rows in the index (one per package version per run that decided it)
        versions:
          type: integer
          title: Versions
          description: distinct package versions examined
        findings:
          type: integer
          title: Findings
        tools:
          type: integer
          title: Tools
        runs:
          items:
            $ref: '#/components/schemas/RunRef'
          type: array
          title: Runs
          description: every served run in the index, oldest first
        candidate_runs:
          items:
            type: string
          type: array
          title: Candidate Runs
          description: runs in the index that are not served (held by the promotion gate, or not yet promoted); nothing is answered from them
        index_sha256:
          type: string
          title: Index Sha256
        index_schema:
          type: string
          title: Index Schema
          description: 'the schema of the index served: the current one or the one before it'
        keys:
          type: string
          enum:
          - configured
          - not configured
          title: Keys
          description: whether this service can check an API key at all; when it cannot, every key is refused and a call without one is answered as ever
          default: not configured
        first_party:
          type: string
          enum:
          - configured
          - not configured
          title: First Party
          description: whether the web app and the monitoring job can prove who they are to this service; when they cannot, their calls are keyless
          default: not configured
        last_promotion:
          anyOf:
          - $ref: '#/components/schemas/LastPromotion'
          - type: 'null'
          description: the last promotion recorded beside the index (last-promotion.json, written by every promotion and nothing else); null until one is recorded
        served_run_is_last_promoted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Served Run Is Last Promoted
          description: 'whether run_id is the run the last promotion served: false means something other than a promotion changed the run served, which the uptime check alerts on; null while no promotion is recorded'
        loaded_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Loaded At
        checked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Checked At
      type: object
      required:
      - status
      - run_id
      - methodology_version
      - methodology_sha256
      - methodology_url
      - rows
      - versions
      - findings
      - tools
      - runs
      - candidate_runs
      - index_sha256
      - index_schema
      - loaded_at
      - checked_at
      title: Health