# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:`).