git.stella-ops.org/docs/api/score-replay-api.md

Score API Reference (Platform)

Module: Platform WebService
Base route: /api/v1/score

Scope note: this page documents the Platform score API.
Scanner score replay endpoints are implemented separately at:

• primary: /api/v1/scans/{scanId}/score/replay|bundle|verify|history
• compatibility aliases: /api/v1/score/{scanId}/replay|bundle|verify|history See src/Scanner/StellaOps.Scanner.WebService/Endpoints/ScoreReplayEndpoints.cs and docs/modules/scanner/architecture.md.

Overview

The score API exposes deterministic score computation, replay verification, and explanation payloads. All responses are tenant-scoped and wrapped in the standard Platform envelope.

Authentication and tenant context

• Bearer token authentication is required.
• Required policies: platform.score.read, platform.score.evaluate
• Tenant context is resolved from authenticated context/middleware and must be present.

Response envelope

Single-item responses return:

{
  "tenantId": "tenant-a",
  "actorId": "user-1",
  "dataAsOf": "2026-02-26T12:00:00Z",
  "cached": true,
  "cacheTtlSeconds": 300,
  "item": { }
}

Endpoints

POST /api/v1/score/evaluate

Computes unified score from provided signal inputs.

Response highlights:

• unknowns: deterministic list of missing signal dimensions when snapshot data is available.
• proof_ref: deterministic proof locator (proof://score/<normalized-digest>).

GET /api/v1/score/history?cve_id=<id>&purl=<optional>&limit=<optional>

Returns historical score records for the requested CVE and optional PURL.

GET /api/v1/score/{scoreId}

Returns persisted score by score identifier.

GET /api/v1/score/{scoreId}/replay

Returns replay payload for deterministic verification.

POST /api/v1/score/verify

Verifies replay payload and returns deterministic verification status fields.

Verification details:

• verified is computed from deterministic comparison checks (score_matches, digest_matches) and available signature/Rekor checks.
• differences includes field-level mismatch reasons (for example final_score, ews_digest, signed_replay_log_dsse).
• malformed replay envelopes return a deterministic differences entry rather than synthetic success.

GET /api/v1/score/explain/{digest}

Returns canonical score explanation contract for a persisted replay digest.

Success payload (item) schema:

{
  "contractVersion": "score.explain.v1",
  "digest": "sha256:...",
  "scoreId": "score_...",
  "finalScore": 62,
  "bucket": "Investigate",
  "computedAt": "2026-02-26T12:00:00Z",
  "deterministicInputHash": "sha256:...",
  "replayLink": "/api/v1/score/score_x/replay",
  "factors": [
    {
      "name": "reachability",
      "weight": 0.25,
      "value": 1.0,
      "contribution": 0.25
    }
  ],
  "sources": [
    {
      "sourceType": "score_history",
      "sourceRef": "score-history:score_x",
      "sourceDigest": "sha256:..."
    }
  ]
}

Deterministic error schema (/explain/{digest})

Error payload:

{
  "code": "not_found | invalid_input | backend_unavailable",
  "message": "deterministic human-readable message",
  "digest": "sha256:..."
}

Status mapping:

• 400 -> invalid_input
• 404 -> not_found
• 503 -> backend_unavailable

Client integration notes

• CLI and Web clients must treat score.explain.v1 as the current canonical contract.
• Clients must not synthesize explanation factors when 404 or 503 is returned.
• digest values are normalized to lowercase with explicit algorithm prefix (sha256:).