Excititor Advisory-AI Evidence APIs (projection + chunks)

Audience: Advisory AI, VEX Lens, and integration engineers building on Excititor’s read-only evidence surfaces. Covers: the evidence read APIs introduced in Sprints 119–120 — the observation projection, the evidence chunk stream, and attestation lookup.

These endpoints expose raw VEX statements with full provenance and signature metadata, and nothing more — Excititor is aggregation-only, so no consensus, severity merging, or reachability is applied. See the Excititor architecture dossier for the aggregation guardrails and Observability for the metrics these endpoints emit.

Endpoints at a glance

EndpointMethodResponsePurpose
/v1/vex/observations/{vulnerabilityId}/{productKey}GETJSONProjection of raw VEX statements for one vulnerability/product.
/v1/vex/evidence/chunksGETNDJSON streamStreamed evidence chunks for citation and large result sets.
/v1/vex/attestations/{attestationId}GETJSONAttestation provenance lookup (supplier ↔ observation ↔ product).

All endpoints require a bearer token with the vex.read scope.

Scope and determinism

/v1/vex/observations/{vulnerabilityId}/{productKey}

/v1/vex/evidence/chunks

OpenAPI (excerpt):

paths:
  /v1/vex/evidence/chunks:
    get:
      summary: Stream evidence chunks for a vulnerability/product
      parameters:
        - in: query
          name: vulnerabilityId
          schema: { type: string }
          required: true
        - in: query
          name: productKey
          schema: { type: string }
          required: true
        - in: query
          name: providerId
          schema: { type: string }
          description: Comma-separated provider ids
        - in: query
          name: status
          schema: { type: string }
          description: Comma-separated VEX statuses
        - in: query
          name: since
          schema: { type: string, format: date-time }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 2000, default: 500 }
      responses:
        "200":
          description: NDJSON stream of VexEvidenceChunkResponse
          headers:
            Excititor-Results-Total: { schema: { type: integer } }
            Excititor-Results-Truncated: { schema: { type: boolean } }
          content:
            application/x-ndjson:
              schema:
                type: string
                description: One JSON object per line (VexEvidenceChunkResponse)

Example (curl):

curl -s -H "Authorization: Bearer <token>" \
     -H "X-StellaOps-TenantId: acme" \
     "https://exc.example.test/v1/vex/evidence/chunks?vulnerabilityId=CVE-2025-0001&productKey=pkg:docker/demo&limit=2" |
  head -n 2

Sample NDJSON line:

{"observationId":"provider-a:4d2f...","linksetId":"CVE-2025-0001:pkg:docker/demo","vulnerabilityId":"CVE-2025-0001","productKey":"pkg:docker/demo","providerId":"provider-a","status":"Affected","justification":"ComponentNotPresent","detail":"demo detail","scopeScore":0.9,"firstSeen":"2025-11-10T12:00:00Z","lastSeen":"2025-11-12T12:00:00Z","scope":{"key":"pkg:docker/demo","name":"demo","version":"1.0.0","purl":"pkg:docker/demo","cpe":null,"componentIdentifiers":["component-a"]},"document":{"digest":"sha256:e7...","format":"sbomcyclonedx","sourceUri":"https://example.test/vex.json","revision":"r1"},"signature":{"type":"cosign","subject":"demo","issuer":"issuer","keyId":"kid","verifiedAt":"2025-11-12T12:00:00Z","transparencyRef":null},"metadata":{}}

/v1/vex/attestations/{attestationId}

Error model

Backwards compatibility

References