# Excititor VEX linkset APIs (observations + linksets)

> Draft examples for Sprint 119 (EXCITITOR-LNM-21-203). Aligns with WebService endpoints implemented in `src/Excititor/StellaOps.Excititor.WebService/Program.cs`.

## /v1/vex/observations

### List
```
GET /v1/vex/observations?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&providerId=ubuntu-csaf&status=affected&limit=2
Headers:
  Authorization: Bearer <token>
  X-Tenant: default
Response 200 (application/json):
{
  "items": [
    {
      "tenant": "default",
      "observationId": "vex:obs:sha256:...",
      "providerId": "ubuntu-csaf",
      "document": {
        "digest": "sha256:...",
        "uri": "https://example.com/csaf/1.json",
        "signature": null
      },
      "scope": {
        "vulnerabilityId": "CVE-2024-0001",
        "productKey": "pkg:maven/org.demo/app@1.2.3"
      },
      "statements": [
        {
          "vulnerabilityId": "CVE-2024-0001",
          "productKey": "pkg:maven/org.demo/app@1.2.3",
          "status": "affected",
          "justification": {
            "type": "component_not_present",
            "reason": "Not shipped in base profile"
          },
          "signals": { "severity": { "score": 7.5 } },
          "provenance": {
            "providerId": "ubuntu-csaf",
            "sourceId": "USN-9999-1",
            "fieldMasks": ["statements"]
          }
        }
      ],
      "linkset": {
        "aliases": ["USN-9999-1"],
        "purls": ["pkg:maven/org.demo/app"],
        "cpes": [],
        "references": [{"type": "advisory", "url": "https://..."}],
        "disagreements": []
      },
      "createdAt": "2025-11-18T12:34:56Z"
    }
  ],
  "nextCursor": "eyJ2dWxuZXJhYmlsaXR5SWQiOiJDVkUtMjAyNC0wMDAxIiwiY3JlYXRlZEF0IjoiMjAyNS0xMS0xOFQxMjozNDo1NloifQ=="
}
```

### Get by key
```
GET /v1/vex/observations/CVE-2024-0001/pkg:maven/org.demo/app@1.2.3
Headers: Authorization + X-Tenant
Response 200: same projection shape as list items (single object).
```

## /v1/vex/linksets
```
GET /v1/vex/linksets?vulnerabilityId=CVE-2024-0001&productKey=pkg:maven/org.demo/app@1.2.3&status=affected&limit=2
Headers: Authorization + X-Tenant
Response 200:
{
  "items": [
    {
      "linksetId": "CVE-2024-0001:pkg:maven/org.demo/app@1.2.3",
      "tenant": "default",
      "vulnerabilityId": "CVE-2024-0001",
      "productKey": "pkg:maven/org.demo/app@1.2.3",
      "providers": ["ubuntu-csaf", "suse-csaf"],
      "statuses": ["affected", "fixed"],
      "aliases": ["USN-9999-1"],
      "purls": ["pkg:maven/org.demo/app"],
      "cpes": [],
      "references": [{"type": "advisory", "url": "https://..."}],
      "disagreements": [{"providerId": "suse-csaf", "status": "fixed", "justification": null, "confidence": null}],
      "observations": [
        {"observationId": "vex:obs:...", "providerId": "ubuntu-csaf", "status": "affected", "severity": 7.5},
        {"observationId": "vex:obs:...", "providerId": "suse-csaf", "status": "fixed", "severity": null}
      ],
      "createdAt": "2025-11-18T12:34:56Z"
    }
  ],
  "nextCursor": null
}
```

## Notes
- Pagination: `limit` (default 200, max 500) + `cursor` (opaque base64 of `vulnerabilityId` + `createdAt`).
- Filters: `vulnerabilityId`, `productKey`, `providerId`, `status`; multiple query values allowed.
- Headers: `Excititor-Results-Count`, `Excititor-Results-Cursor` (observations) and `Excititor-Results-Total` / `Excititor-Results-Truncated` (chunks) already implemented.
- Determinism: responses sorted by `vulnerabilityId`, then `productKey`; arrays sorted lexicographically.

## SDK generation
- Use this file plus `vex_observations.md` as the source of truth for SDK examples in EXCITITOR-LNM-21-203.