Search and vulnerability associations
Availability and authentication
CVE/KEV selectors, observed_products explanations and badge search criteria are described in the personal OpenAPI contract. These searches use existing observations and catalogue associations; they do not confirm a vulnerability or start a scan.
Personal integrations use /api/v2/common/data with a personal API key in X-API-KEY, or Authorization: Bearer carrying a personal key or OAuth access token with profundis.read. Every data request requires a current paid subscription or purchased credit balance above zero. Field permissions and available credits still apply. A free enrichment operation does not remove this access requirement.
Browser calls use /api/v2/data with a session and CSRF protection for POST requests. They are a separate surface; see Session contracts.
Search existing observations
POST /search combines the relevant hosts, DNS, certificate (vhosts) and WHOIS datasets. Send stream: false for one JSON response:
POST /api/v2/common/data/search
X-API-KEY: <personal-key>
Content-Type: application/json
{"raw_query":"host:example.com AND kev:true","time_frame":"all_time","per_type_limit":20,"stream":false}
This example searches existing observations. The body is limited to 4 KiB; the trimmed query must be nonempty and at most 512 UTF-8 bytes. time_frame accepts all_time, last_24h, last_7d, last_30d or this_year. The per-dataset limit defaults to 20; positive values are capped at 25. broad: true disables smart interpretation of bare inputs while retaining permissions and query validation.
The initial query is charged according to its target datasets. POST /search/more loads one dataset using raw_query, dataset (hosts, dns, vhosts, whois), page ≥ 2 and the same time_frame and effective per_type_limit. Additional pages use the dataset's depth pricing. GET /search/fields returns the searchable vocabulary without a search charge; a listed field may still require a higher entitlement.
With stream omitted or true, the response is SSE. JSON data chunks identify their type as partial, results, facets or final; retain outcomes through the final chunk. For JSON and streaming responses, inspect partial, per_type_status, lower_bound, per_type_failed, per_type_timed_out and per_type_capped when present. Dataset states include ok, timeout, busy, error, invalid_query and cancelled. A failed or partial dataset does not establish that it contains zero matches.
A stream can also terminate with an error chunk. Treat a connection ending without a final result as incomplete.
CVE and KEV selectors
These selectors apply to hosts observations:
| Selector | Meaning |
|---|---|
cve:CVE-2021-41773 | Association with this catalogue advisory |
cve:CVE-2024-* | Associations with advisories under this CVE prefix |
cve:* | At least one catalogue CVE association |
kev:true | At least one associated advisory in the available KEV catalogue |
kev:false | Negative selector over the indexed association; never proof of safety |
A bare exact CVE identifier is also recognized by unified search. Prefix wildcards must be a supported trailing CVE prefix; cve:apache, internal wildcards and kev:* are invalid. Use Boolean expressions to combine these fields with host criteria. Neither field is a sortable or aggregatable stored host attribute.
These results associate observed software identities with catalogue conditions. They do not confirm configuration, exploitability, ownership or the current state of a server. Missing versions, incomplete observations and unavailable catalogue data remain unknown. KEV describes known exploitation of an advisory in the catalogue; it does not prove exploitation of the returned asset.
Explain the matched product and version
POST /enrich/vulnerabilities reads the catalogue without charging search credits or contacting the asset. The account limit is 60 requests per minute across personal and organization enrichment; honor Retry-After on HTTP 429.
Prefer the opaque vulnerability_ref returned on a host observation (raw.vulnerability_ref in unified results, or data[].vulnerability_ref in granular results):
{"reference":"<vulnerability_ref-from-the-result>"}
References expire after 24 hours. They authorize only advisory enrichment for the returned software observations; they do not grant access to a host record or workspace. Do not decode or construct them. Alternatively, entitled callers may submit {"cpes":["<precise-observed-CPE>"]} with 1–8 CPEs. Raw CPE input on the personal surface requires the CPE field entitlement, currently Enterprise. Send one input form, not both; body limit is 100 KiB.
Each returned finding includes id, advisory details, nullable kev, additional_conditions, and observed_products: an array of {vendor, product, version} associated with that CVE. Do not attach every technology on the host to every finding. A schematic example is:
{
"id": "CVE-2021-41773",
"observed_products": [{"vendor":"apache","product":"http_server","version":"2.4.49"}]
}
This fragment illustrates an association, not an observed customer finding or active test result. Reference-based responses keep CPE identifiers private (cpes: null, empty evaluation cpe); the product/version explanation remains available.
Always read top-level evaluated_at, kev_source, and each evaluation's status, complete, reason, source, total and findings. status is matched, no_match or indeterminate. HTTP 200 can include incomplete or indeterminate evaluations. kev: null means unknown, not false. Only a complete no_match describes a completed negative catalogue lookup; even that is not a security assessment of the asset.
Invalid input/reference returns 422, a forbidden raw-CPE request 403, and reference lookup failure may return 503. Check the HTTP status and error code rather than retrying an invalid reference indefinitely.
Badge evidence and related searches
POST /enrich/badges adds contextual badges to returned result items without a search charge. A badge may contain an optional search object with field, value, match (exact, prefix, suffix), query and datasets. This represents the indexed criterion supporting that badge; it is not an exact query for the badge's display label.
Its body is {"items":[{"key":"row-1","type":"host","value":"example.com"}]}. Up to 50 items fit in a 256 KiB request; keys must be unique and at most 256 UTF-8 bytes. Supported item types are host, domain, ip, cert, whois and dns. An optional record object (at most 4 KiB) is accepted for compatibility but does not become trusted evidence. At most two enrichment batches per account can run concurrently across surfaces; a third receives 429 background_busy.
Use the supplied query only when the user chooses to start a related search. That search has normal credit, dataset and field restrictions. Do not invent tag:<badge-id> syntax. Some historical, privacy or combined evidence has no supported selector; an absent search is intentional. Inspect partial before treating an absent badge as a negative conclusion.