[afoote-mitre]

Summary

Define an API-owned response contract for POST /search and add non-fatal warnings for requested CVE IDs from years before CVE Records exist.

Why These Changes Were Needed

Decouple the API from OpenSearch responses

The previous success payload returned OpenSearch response and hit objects directly. That exposed implementation details such as index names, shard metadata, scores, hit wrappers, and backend timing while requiring clients to understand OpenSearch-specific structures.

The new response contains, in order:

• apiVersion
• status
• warnings
• pagination
• records

Complete CVE Records are returned directly in records. Search-backend timing remains available to internal telemetry but is no longer included in the public response.

Primary files:

• controllers/searchController.js
• utils/searchResponseBuilder.js
• routes/swagger.js
• api-docs/openapi.json

Make bounded semantic totals explicit

Semantic post-filter searches inspect at most 10,000 candidates. When that ceiling is reached, the response now sets pagination.totalIsExact to false and places a SEMANTIC_CANDIDATE_LIMIT_REACHED warning before the records. Direct searches and semantic searches below the ceiling report exact totals.

Primary files:

• controllers/searchController.js
• utils/searchResponseBuilder.js
• README.md
• routes/swagger.js

Remove backend-specific public errors

Search dependency failures now return the platform-neutral SEARCH_UNAVAILABLE error instead of naming OpenSearch in the public error code and message.

Primary files:

• controllers/searchController.js
• utils/errors.js
• routes/index.js

Explain pre-1999 CVE ID results without rejecting mixed requests

CVE Records do not exist for years before 1999. These syntactically valid IDs continue to produce zero matches rather than an HTTP error. A successful response now includes CVE_IDS_NOT_RETURNED with the affected IDs. When a request contains both pre-1999 and supported-year IDs, matching supported-year records are still returned.

Primary files:

• utils/searchResponseBuilder.js
• controllers/searchController.js
• utils/constants.js
• routes/swagger.js
• README.md