API Documentation

Authentication

Create a credential in API Tokens. Supply it in the Authorization header of every API request.

Authorization: Bearer YOUR_TOKEN

Tokens are displayed once. Use HTTPS and keep credentials on a trusted backend—never embed bearer tokens in browser JavaScript or public repositories.

Endpoints

Request headers

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Single-product request

POST /api/v1/assess/
{
  "vendor": "apache",
  "product": "http_server",
  "version": "2.4.49"
}

vendor and product are required strings, maximum 128 printable characters. version is optional and may be empty. Extra fields and duplicate JSON keys are rejected.

Bulk request

POST /api/v1/assess/bulk/
{
  "items": [
    {"vendor":"apache", "product":"http_server", "version":"2.4.49"},
    {"vendor":"huawei", "product":"hg523e", "version":""}
  ]
}

Bulk accepts 1–100 items. Every item follows the same validation rules. Invalid items reject the whole request; response rows maintain input order.

Response schema · HTTP 200

The example below illustrates the response structure only. Values are not measured ROJX predictions or claims about a particular CVE.

{
  "run_id": 12,
  "mode": "single",
  "rows_total": 1,
  "rows_with_candidates": 1,
  "results": [{
    "row": 1,
    "vendor": "example_vendor",
    "product": "example_product",
    "version": "1.0",
    "status": "CANDIDATES_FOUND",
    "retrieval_route": "vendor_product",
    "candidates": [{
      "cve": "CVE-2025-12345",
      "rank": 1,
      "ai_score": 0.82,
      "v3_score": 0.75,
      "vendor": "example_vendor",
      "product": "example_product",
      "description": "Illustrative CVE description from the local index.",
      "description_source": "assessment_index",
      "cvss": {"score": 7.5, "severity": "HIGH", "vector": "illustrative"},
      "applicability": "INDETERMINATE",
      "applicability_reason": "EXAMPLE_REASON_CODE",
      "applicability_explanation": "The stored NVD assessment did not reach a conclusive applicability decision.",
      "applicability_basis": "EXACT_INDEXED_PRODUCT_VERSION",
      "applicability_nvd_last_modified": null,
      "applicability_engine_version": null,
      "applicability_target_cpe": null
    }]
  }]
}

Candidate fields and interpretation

The primary response fields are described below. Technical audit metadata is available separately for developers who need it.

Important: cached applicability is reused only when vendor, product and a concrete version match the indexed CVE identity. For other versions or identities it is NOT_EVALUATED—never automatically NOT_APPLICABLE. INDETERMINATE indicates an attempted evaluation without a conclusive outcome. ROJX does not verify a live host or execute a penetration test.

Saved results and historical metadata

GET /api/v1/results/{run_id}/ includes the saved ranking and cached applicability decisions. Older results that did not store descriptions/CVSS can receive these fields from the currently configured local index when read, without changing the saved run or re-ranking it. Check description_source to identify this situation; current-index metadata can differ from metadata available at the time of the original analysis.

CSV exports

The browser and bearer-token CSV downloads include description, cvss_score, cvss_severity, cvss_vector, description_source and applicability_explanation. Existing columns including v3_score, applicability_reason, applicability_basis, nvd_last_modified and target_cpe remain available. CSV exports include every result regardless of page navigation in the browser.

Validation error · HTTP 422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid product data.",
    "details": [{"field": "vendor", "message": "Required, non-empty string."}]
  }
}

Error codes

Python example

import requests
api = "https://YOUR_HOST/api/v1/assess/"
response = requests.post(api, headers={
    "Authorization": "Bearer YOUR_TOKEN"
}, json={"vendor": "apache", "product": "http_server", "version": "2.4.49"}, timeout=120)
response.raise_for_status()
for c in response.json()["results"][0]["candidates"]:
    print(c["cve"], c.get("description"), c.get("cvss"), c.get("applicability"))

JavaScript example (trusted server-side environment)

// Node.js 18+; never expose ROJX_API_TOKEN in browser code.
const response = await fetch("https://YOUR_HOST/api/v1/assess/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROJX_API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({vendor:"apache", product:"http_server", version:"2.4.49"})
});
const data = await response.json();
if (!response.ok) throw new Error(data.error?.code || `HTTP ${response.status}`);
for (const candidate of data.results[0].candidates) {
  console.log(candidate.cve, candidate.description, candidate.cvss,
              candidate.applicability, candidate.ai_score);
}

Use the returned run_id for GET /api/v1/results/{run_id}/ or its CSV download endpoint. API execution remains synchronous; production timeouts, quotas and authentication should be reviewed before public deployment.