Attestari Remote API

openapi: 3.2.0
info:
  title: Attestari lookup Remote 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: Remote
paths:
  /v1/remote/{name}:
    get:
      summary: 'a remote MCP server''s watch record: watched, not graded'
      description: 'A remote''s watch record (publish contract section 13): without a key, the free summary (`watch_summary`,

        cached as a public answer is); with one, the whole record, counted as a lookup (Q2, decided

        attestari-engineers@2026-10-24). A remote is never graded; neither answer carries a grade. A remote''s name has

        no query, so a request with one is refused rather than answered as if it had none.'
      operationId: remote_v1_remote__name__get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: not watched
        '400':
          description: not a remote's name
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Remote
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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError