git.stella-ops.org/docs/modules/concelier/api/evidence-batch.md

Concelier Evidence Batch API (draft v1)

Path: POST /v1/evidence/batch
Auth: same as other advisory read endpoints; requires tenant header X-Stella-Tenant.
Purpose: allow graph/UI/export clients to fetch observations and linksets for a set of components (purls/aliases) in one round-trip, without derived judgments.

Request

{
  "items": [
    {
      "componentId": "component-a",
      "purls": ["pkg:maven/org.example/app@1.0.0"],
      "aliases": ["CVE-2025-0001"]
    }
  ],
  "observationLimit": 50,
  "linksetLimit": 50
}

Field rules:

• items is required and must be non-empty.
• Each item must supply at least one identifier (purls or aliases).
• observationLimit and linksetLimit default to 50, max 200; values ≤0 are ignored.

Response

{
  "items": [
    {
      "componentId": "component-a",
      "observations": [
        {
          "id": "obs:123",
          "tenant": "demo",
          "aliases": ["CVE-2025-0001"],
          "purls": ["pkg:maven/org.example/app@1.0.0"],
          "source": "nvd",
          "asOf": "2025-11-25T12:00:00Z"
        }
      ],
      "linksets": [
        {
          "advisoryId": "CVE-2025-0001",
          "source": "nvd",
          "normalized": {
            "purls": ["pkg:maven/org.example/app@1.0.0"]
          },
          "createdAt": "2025-11-25T12:00:00Z"
        }
      ],
      "hasMore": false,
      "retrievedAt": "2025-11-25T12:00:01Z"
    }
  ]
}

Determinism:

• Results ordered by provider ordering returned from storage; clients must not assume stable sort keys beyond the documented arrays.
• retrievedAt is server UTC ISO-8601.
• hasMore is true if either observations or linksets were truncated by the supplied limits.

Notes:

• No derived severity/weights are added; payloads mirror stored observations/linksets.
• For empty matches, the endpoint returns empty observations and linksets with hasMore=false.

Fixtures:

• Sample request/response above; further fixtures can be generated from docs/samples/lnm/ data once LNM v1 fixtures are refreshed.

Changelog:

• 2025-11-25: initial draft and implementation aligned with /v1/evidence/batch endpoint.