API Documentation

The OpenCVE REST API lets your own tools interact with OpenCVE programmatically. Connect it to your CMDB, inventory, ITSM, SOAR, SIEM, or internal scripts to build vulnerability workflows that fit the way your team already works.

The API v2 is available at https://app.opencve.io/api/v2/.

Interactive documentation is available on Swagger: https://app.opencve.io/api/v2/docs/.

With API v2, you can both read and write data:

• Read: browse the CVE catalog, search with advanced filters, list vendors and products, inspect project CVEs, read reports, and review automation execution history.
• Write: manage projects, update subscriptions, triage CVEs (status and assignee), configure notifications and automations, and manage organization members.

Quick start

Set your organization API token in your shell, then list CVEs from the catalog:

export OPENCVE_TOKEN="opc_org.<token_id>.<secret>"

curl https://app.opencve.io/api/v2/cves \
  -H "Authorization: Bearer $OPENCVE_TOKEN" \
  -H "Accept: application/json"

Example

Sync your software inventory with OpenCVE by replacing all subscriptions of a project in a single request:

curl -X PUT \
  "https://app.opencve.io/api/v2/organizations/acme/projects/production/subscriptions" \
  -H "Authorization: Bearer $OPENCVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendors": ["python", "microsoft"],
    "products": {
      "apache": ["http_server", "airflow"],
      "fortinet": ["fortios"]
    }
  }'

This request replaces the entire subscription set of the project. You can subscribe to whole vendors (e.g. python, microsoft) and specific products (e.g. apache/http_server) in a single operation.

Authentication

The API v2 uses Organization API Tokens only. They provide a secure way to authenticate requests without relying on user credentials, and are designed for automation and machine-to-machine access (scripts, CI/CD pipelines, SIEM integrations, and more).

Each organization can create multiple tokens and revoke them at any time. If a token is compromised, it can be revoked without impacting user accounts or other tokens.

Tokens use the Bearer authentication scheme and must be sent in the Authorization header:

Authorization: Bearer opc_org.<token_id>.<secret>

Organization API tokens can be created from the organization settings page. For security reasons, the token secret is displayed only once at creation time. Make sure to copy and store it securely, for example in an environment variable:

export OPENCVE_TOKEN="opc_org.<token_id>.<secret>"

On OpenCVE Community, tokens support two access modes:

• Read-only: can only perform read operations
• Read-write: can perform both read and write operations

On OpenCVE Cloud, you can create tokens with granular scopes to follow the principle of least privilege. For example:

• A monitoring dashboard token limited to catalog:read and tracker:read
• An onboarding pipeline token with projects:read and subscriptions:write to sync subscriptions from your inventory without granting full write access

A write scope automatically includes read access to the same resource. For example, projects:write also grants projects:read.

Availability

Granular API token scopes are available on OpenCVE Cloud, starting from the Pro plan. On OpenCVE Community, tokens support read-only or read-write access only.

Pagination

Some endpoints can return lots of results (listing CVEs, for instance). In these cases, results are paginated with the page parameter.

Example with the list of CVEs:

curl -H "Authorization: Bearer $OPENCVE_TOKEN" \
    "https://app.opencve.io/api/v2/cves?page=2"

{
  "count": 262939,
  "next": "https://app.opencve.io/api/v2/cves?page=3&page_size=20",
  "previous": "https://app.opencve.io/api/v2/cves?page=1&page_size=20",
  "results": [
    ...
  ]
}

The next and previous keys help you navigate through pages. The default page size is 20 items. You can adjust it with the page_size parameter (maximum 100).

When no result is found (the page parameter is too high), a 404 HTTP status code is returned.

Error responses

When a request fails, the API returns a structured JSON error:

{
  "error": {
    "code": "read_only_token",
    "message": "This token is read-only and cannot perform write operations."
  }
}

Every error includes a code and a message. Some errors include extra fields such as details (field-level validation errors) or required_scope (when the token lacks a specific scope).

Error codes

Code	HTTP status	Description
invalid_token	401	Missing, malformed, revoked, or invalid Bearer token
not_found	404	Resource not found (including an out-of-range pagination page)
permission_denied	403	The request is not allowed
read_only_token	403	A read-only token was used for a write operation
missing_scope	403	The token does not have the required scope for this operation
validation_error	400	Invalid request body or query parameters

Examples

{
  "error": {
    "code": "read_only_token",
    "message": "This token is read-only and cannot perform write operations."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Validation error.",
    "details": {
      "vendors": ["Vendor does not exist: 'foobar'."]
    }
  }
}

Explore the API (Swagger)

All endpoints, parameters, request bodies, and response schemas are documented in the interactive Swagger UI: https://app.opencve.io/api/v2/docs/.

The API is organized around these main areas:

• cves: CVE catalog, details, and change history
• vendors: vendors, products, and related CVEs
• weaknesses: CWE weaknesses and related CVEs
• organizations: organization settings, members, and audit logs
• projects: projects, subscriptions, CVE tracker, notifications, automations, and reports

Use Swagger to try requests directly in your browser and copy ready-to-use examples.

API v1 (deprecated)

The API v1 (/api/) is deprecated and no longer receives new features. New integrations should use API v2.

The v1 documentation is archived here.