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