Attestari Manifest API

openapi: 3.2.0
info:
  title: Attestari lookup Manifest 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: Manifest
paths:
  /v1/manifest/{ecosystem}/{name}/{version}:
    get:
      summary: the attested manifest of one package version
      operationId: manifest_version_v1_manifest__ecosystem___name___version__get
      parameters:
      - name: ecosystem
        in: path
        required: true
        schema:
          type: string
          description: npm or pypi
          title: Ecosystem
        description: npm or pypi
      - name: name
        in: path
        required: true
        schema:
          type: string
          description: the package name; for a scoped npm package use the scoped route or @scope/name
          title: Name
        description: the package name; for a scoped npm package use the scoped route or @scope/name
      - name: version
        in: path
        required: true
        schema:
          type: string
          description: the exact published version
          title: Version
        description: the exact published version
      - name: methodology
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'answer with the latest decision made under this methodology version (an older one is listed under `superseded`); default: the decision under the newest methodology that examined the version'
          title: Methodology
        description: 'answer with the latest decision made under this methodology version (an older one is listed under `superseded`); default: the decision under the newest methodology that examined the version'
      - name: run
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: answer with the decision this run made (every decision names its run under `superseded`)
          title: Run
        description: answer with the decision this run made (every decision names its run under `superseded`)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
        '401':
          description: 'no key, or a key that is not accepted: the manifest is part of the full report'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRequired'
        '403':
          description: 'the key''s plan does not include the attested manifest (`plan_without_manifest`: it is the Platform tier''s), or its organization has no plan that includes lookups (`subscription_required`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRequired'
        '404':
          description: no decision for this package version in the served run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotExamined'
        '503':
          description: the key could not be checked, or part of the record could not be read; nothing is answered in part
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Manifest
  /v1/manifest/{ecosystem}/{scope}/{name}/{version}:
    get:
      summary: the attested manifest of one version of a scoped npm package
      operationId: manifest_scoped_v1_manifest__ecosystem___scope___name___version__get
      parameters:
      - name: ecosystem
        in: path
        required: true
        schema:
          type: string
          description: npm or pypi
          title: Ecosystem
        description: npm or pypi
      - name: scope
        in: path
        required: true
        schema:
          type: string
          description: the npm scope, with its @
          title: Scope
        description: the npm scope, with its @
      - name: name
        in: path
        required: true
        schema:
          type: string
          description: the package name; for a scoped npm package use the scoped route or @scope/name
          title: Name
        description: the package name; for a scoped npm package use the scoped route or @scope/name
      - name: version
        in: path
        required: true
        schema:
          type: string
          description: the exact published version
          title: Version
        description: the exact published version
      - name: methodology
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'answer with the latest decision made under this methodology version (an older one is listed under `superseded`); default: the decision under the newest methodology that examined the version'
          title: Methodology
        description: 'answer with the latest decision made under this methodology version (an older one is listed under `superseded`); default: the decision under the newest methodology that examined the version'
      - name: run
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: answer with the decision this run made (every decision names its run under `superseded`)
          title: Run
        description: answer with the decision this run made (every decision names its run under `superseded`)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
        '401':
          description: 'no key, or a key that is not accepted: the manifest is part of the full report'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRequired'
        '403':
          description: 'the key''s plan does not include the attested manifest (`plan_without_manifest`: it is the Platform tier''s), or its organization has no plan that includes lookups (`subscription_required`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyRequired'
        '404':
          description: no decision for this package version in the served run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotExamined'
        '503':
          description: the key could not be checked, or part of the record could not be read; nothing is answered in part
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Manifest
components:
  schemas:
    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
    ManifestLinks:
      properties:
        definition:
          anyOf:
          - type: string
          - type: 'null'
          title: Definition
        verdict:
          type: string
          title: Verdict
      type: object
      required:
      - definition
      - verdict
      title: ManifestLinks
    NotExamined:
      properties:
        status:
          type: string
          const: not_examined
          title: Status
        ecosystem:
          type: string
          title: Ecosystem
        name:
          type: string
          title: Name
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        run_id:
          type: string
          title: Run Id
        methodology_version:
          type: string
          title: Methodology Version
        detail:
          type: string
          title: Detail
      type: object
      required:
      - status
      - ecosystem
      - name
      - version
      - run_id
      - methodology_version
      - detail
      title: NotExamined
    Provenance:
      properties:
        run_id:
          type: string
          title: Run Id
        decided_at:
          type: string
          title: Decided At
        code_commit:
          type: string
          title: Code Commit
        extractor_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Extractor Version
          description: the surface extractor that read the package; null on a row that predates the record
        analyzer_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Analyzer Model
        prompt_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Sha256
        verifier_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Verifier Version
        manifest_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Manifest Hash
        manifest_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Manifest Reason
        presented_manifest_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Presented Manifest Hash
          description: 'the presented manifest (methodology 2.9.0, section 7): what a client can check before it starts against the tools a server presents (each tool''s name and description, white space collapsed; no schema). Null with a reason when there is none'
        presented_manifest_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Presented Manifest Reason
          description: why there is no presented manifest hash; null when there is one
      type: object
      required:
      - run_id
      - decided_at
      - code_commit
      - extractor_version
      - analyzer_model
      - prompt_sha256
      - verifier_version
      - manifest_hash
      - manifest_reason
      title: Provenance
    KeyRequired:
      properties:
        status:
          type: string
          enum:
          - key_required
          - invalid_key
          - subscription_required
          - plan_without_manifest
          - trial_allowance_reached
          title: Status
        detail:
          type: string
          title: Detail
      type: object
      required:
      - status
      - detail
      title: KeyRequired
    MethodologyRef:
      properties:
        version:
          type: string
          title: Version
          description: the methodology version the decision was made under
        document_sha256:
          type: string
          title: Document Sha256
          description: SHA-256 of the methodology document bytes the decision cites
        policy:
          type: string
          title: Policy
        url:
          type: string
          title: Url
          description: the document at its permanent address
      type: object
      required:
      - version
      - document_sha256
      - policy
      - url
      title: MethodologyRef
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Subject:
      properties:
        ecosystem:
          type: string
          title: Ecosystem
        name:
          type: string
          title: Name
        version:
          type: string
          title: Version
      type: object
      required:
      - ecosystem
      - name
      - version
      title: Subject
    Manifest:
      properties:
        status:
          type: string
          const: examined
          title: Status
        subject:
          $ref: '#/components/schemas/Subject'
        attested:
          type: boolean
          title: Attested
        manifest_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Manifest Hash
        manifest_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Manifest Reason
        previous_manifest_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Previous Manifest Sha256
          description: 'set by a `manifest_changed` event: the manifest hash of the previous examined version of the package, which this version''s manifest hash differs from. Null when there is no event: the hash is unchanged, there is no previous examined version, or either version has no manifest hash. An event is not a finding and has no effect on a grade'
        changed_since:
          anyOf:
          - type: string
          - type: 'null'
          title: Changed Since
          description: 'set by a `manifest_changed` event: the previous examined version, since which the manifest changed; null when there is no event'
        changed_under_same_extractor:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Changed Under Same Extractor
          description: 'set by a `manifest_changed` event: whether both versions were read by the same extractor version. False means the two hashes were computed by different extractors, and the difference may be the instrument''s, not the package''s'
        events_indexed:
          type: boolean
          title: Events Indexed
          description: whether the index served records events at all (schema 6); false on an older index, where the three fields above are null because nothing was compared, not because nothing changed
        tools:
          items:
            $ref: '#/components/schemas/ManifestTool'
          type: array
          title: Tools
        methodology:
          $ref: '#/components/schemas/MethodologyRef'
          description: the methodology version and document hash the manifest was decided under; the same block the verdict carries
        provenance:
          $ref: '#/components/schemas/Provenance'
          description: the run, commit, extractor, analyzer and verifier behind the decision; the same block the verdict carries
        run_id:
          type: string
          title: Run Id
        decided_at:
          type: string
          title: Decided At
        links:
          $ref: '#/components/schemas/ManifestLinks'
      type: object
      required:
      - status
      - subject
      - attested
      - manifest_hash
      - manifest_reason
      - previous_manifest_sha256
      - changed_since
      - changed_under_same_extractor
      - events_indexed
      - tools
      - methodology
      - provenance
      - run_id
      - decided_at
      - links
      title: Manifest
    ManifestTool:
      properties:
        name:
          type: string
          title: Name
        tool_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Hash
        description_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Description Sha256
        schema_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Schema Sha256
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: why the tool has no tool hash; null when it has one
      type: object
      required:
      - name
      - tool_hash
      - description_sha256
      - schema_sha256
      - reason
      title: ManifestTool