# EVC API ## EVC v1.0 ### Before You Begin 1. Go to the [**BlueRock Developers**](https://developers.bluerock.io) portal. 2. [**Sign In**](https://developers.bluerock.io/accounts/login) to auto-register your account. 3. Click your email address in the top-left corner and select **Apps** from the drop down. 4. Select **+NEW APP** and provide an App Name (e.g., `splunk-lookup`) and an optional Description. 5. **Enable** the BlueRock EVC 1.0 API. 6. **Save** your app and save the **Key** associated with your app (to be used as the `X-API-Key`for header-based authentication). {% hint style="warning" %} After creating your app, initial API key activation can take up to 1 business day to complete.\ If your API key is still not active after that time, please [contact us](mailto:research@bluerock.io). {% endhint %} ### Overview At a high level, submitting CVEs for analysis by EVC is a three-step process: 1. Provide the complete list of CVEs you want EVC to analyze. EVC will then return the *subset* of CVEs it immediately *knows* about already. 2. For any previously unknown CVEs, EVC will start a deep research job to exhaustively analyze the remaining CVEs. 3. Once completed, you can either be notified by EVC via a callback or periodically poll EVC for the final job results. {% hint style="danger" %} Deep research jobs usually take about 1-2 hours to complete, depending on the quantity of *unknown* CVEs. {% endhint %} ### Technical Details #### If you have 1-100 CVEs per query... {% stepper %} {% step %} Use the `HTTP POST /search`endpoint with the `application/json` content type. * Where `type`is set to `"query"`and `query`is set to the set of CVEs you want to search for * EVC will provide the initial search results along with a `job_id`, corresponding to the deep research job to analyze any previously unknown CVEs. {% endstep %} {% step %} To check when a deep research job is complete, periodically poll the `HTTP GET /search?job_id=`endpoint with your corresponding `job_id`. * When the `status`field is either `"done"`or `"rejected"`, then the deep research job is complete. * Once complete, the response to this call will be the complete results of all corresponding CVEs in your original `query`. {% endstep %} {% step %} (Optional) Instead of polling, you can request to be notified via a callback when the deep research job completes. * To enable this, specify a `callback_url`along with `callback_header`values (that EVC can use authenticate to your callback service) * Once the deep research job completes, EVC sends a callback as an `HTTP POST`action to your `callback_url` with all `callback_header`values set. * The callback payload in this `HTTP POST` is`{"job_id":"YOUR JOB ID"}`. * Use the `job_id`to query the `HTTP GET /search?job_id=`endpoint to fetch the completed job results. {% endstep %} {% endstepper %} #### If you have more than 100+ CVEs per query... {% stepper %} {% step %} Use the `HTTP POST /search`endpoint with the `multipart/form-data` content type. * Where `type`is set to `"file"`and `file` contains the set of CVEs to query against. * EVC will provide the initial search results along with a `job_id`, corresponding to the deep research job to analyze any previously unknown CVEs. {% endstep %} {% step %} To check when a deep research job is complete, periodically poll the `HTTP GET /search?job_id=`endpoint with your corresponding `job_id`. * When the `status`field is either `"done"`or `"rejected"`, then the deep research job is complete. * Once complete, the response to this call will be the complete results of all corresponding CVEs in your original `query`. {% endstep %} {% step %} (Optional) Instead of polling, you can request to be notified via a callback when the deep research job completes. * To enable this, specify a `callback_url`along with `callback_header`values (that EVC can use authenticate to your callback service) * Once the deep research job completes, EVC sends a callback as an `HTTP POST`action to your `callback_url` with all `callback_header`values set. * The callback payload in this `HTTP POST` is`{"job_id":"YOUR JOB ID"}`. * Use the `job_id`to query the `HTTP GET /search?job_id=`endpoint to fetch the completed job results. {% endstep %} {% endstepper %} ## OpenAPI Swagger {% file src="/files/1LPEQv4OvYvEhw6wlBPO" %} ## API Playground {% openapi src="/files/1LPEQv4OvYvEhw6wlBPO" path="/search" method="post" %} [bluerock-evc-api-1.0.2.yaml](https://312584088-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVePI37p7qZEyuPxALZFF%2Fuploads%2FSNFsDC2RAIeEAZJMvnpW%2Fbluerock-evc-api-1.0.2.yaml?alt=media\&token=a62e6d93-19c8-4e5d-95ef-d12467c2a771) {% endopenapi %} {% openapi src="/files/1LPEQv4OvYvEhw6wlBPO" path="/search" method="get" %} [bluerock-evc-api-1.0.2.yaml](https://312584088-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVePI37p7qZEyuPxALZFF%2Fuploads%2FSNFsDC2RAIeEAZJMvnpW%2Fbluerock-evc-api-1.0.2.yaml?alt=media\&token=a62e6d93-19c8-4e5d-95ef-d12467c2a771) {% endopenapi %} ## FAQ {% stepper %} {% step %} ### What source IP addresses are used by BlueRock EVC to send callbacks? Callbacks generated by BlueRock EVC will originate from Airtable-owned dynamic IP addresses. More information about this can be found [here](https://support.airtable.com/v1/docs/what-are-the-technical-requirements-for-using-airtable#allowlisting-airtable-ip-addresses). {% endstep %} {% step %} ### BlueRock EVC appears to have excluded or ignored some of my CVEs. Why did that happen? BlueRock EVC automatically ignores and omits any CVEs that are currently marked as **Rejected** or **Reserved**. For CVEs that are currently Reserved, wait until the CVE details are **Published** and then retry your query. {% endstep %} {% step %} ### What are the set of CVEs currently known to BlueRock EVC? EVC automatically tracks all MITRE CVEs that were either created or updated by NIST NVD on or after 2025. At the time of this writing, this represents about 10-20% of all CVEs across all time. {% endstep %} {% step %} ### How long do deep research jobs usually take in BlueRock EVC? Deep research jobs usually take 1-2 hours, depending on the quantity of CVEs provided that are initially unknown to BlueRock EVC. {% endstep %} {% step %} ### Are there any plans to have BlueRock EVC retroactively evaluate older CVEs at scale? Not at this time. By simply providing EVC queries of older CVEs, the system will automatically evaluate older CVEs through subsequent deep research jobs. {% endstep %} {% step %} ### For any lookups made to BlueRock EVC, should I store and use those results forever? **No.** As new security mechanisms and features are added to the BlueRock platform, subsequent coverage of existing CVEs may change over time. As such, EVC will periodically reevaluate corresponding coverage as new versions of BlueRock are publicly released. Furthermore, if material details about a CVE change over time, EVC will also reevaluate corresponding coverage, accordingly. In the API output, each corresponding element within the `cve_details`array has an `expires_at` timestamp representing a future expiration date as to how long you should store intermediate results in a local cache. Once expired, it is recommended to re-query the BlueRock EVC for any new information about corresponding coverage for each CVE. {% endstep %} {% step %} ### What about CVEs that evolve over time? How does BlueRock EVC account for those? See earlier answer to question 6. {% endstep %} {% step %} ### What does BlueRock EVC do about CVEs that are Rejected or Reserved? BlueRock EVC ignores and omits any CVEs that are Rejected or Reserved from all outputs. This includes any CVEs that might *look* valid but are not officially published (yet). For any of these CVEs, please resubmit them to EVC once the CVE details are published. {% endstep %} {% step %} ### I have other questions. What do I do? [Contact us](mailto:research@bluerock.io) directly for more information. {% endstep %} {% endstepper %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://evc.bluerock.io/evc-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.