API overview

Browse the Open API documentation

How to use OpenAPI documentation

The API documentation is available at https://public.vulnerablecode.io/api/docs/. To use the endpoints you need to authenticate with an API key. Request your API key from https://public.vulnerablecode.io/account/request_api_key/. Once you have your API key, click on the Authorize button on the top right of the page and enter your API key in the value field with Token prefix, so if your token is “1234567890abcdef” then you have to enter this: Token 1234567890abcdef.

Query for Package Vulnerabilities

The package endpoint allows you to query vulnerabilities by package using a purl or purl fields.

Sample python script:

import requests

# Query by purl
resp = requests.get(
    "https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/log4j@1.2.27",
    headers={"Authorization": "Token 123456789"},
).json()

# Query by purl type, get all the vulnerable maven packages
resp = requests.get(
    "https://public.vulnerablecode.io/api/packages?type=maven",
    headers={"Authorization": "Token 123456789"},
).json()

Sample using curl:

curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/packages?purl=pkg:maven/log4j/log4j@1.2.27

The response will be a list of packages, these are packages that are affected by and/or that fix a vulnerability.

API endpoints reference

There are two primary endpoints:

  • packages/: this is the main endpoint where you can lookup vulnerabilities by package.

  • vulnerabilities/: to lookup by vulnerabilities

And two secondary endpoints, used to query vulnerability aliases (such as CVEs) and vulnerability by CPEs: cpes/ and aliases/

Table for the main API endpoints

Endpoint

Query Parameters

Expected Output

/api/packages

  • purl (string) = package-url of the package

  • type (string) = type of the package

  • namespace (string) = namespace of the package

  • name (string) = name of the package

  • version (string) = version of the package

  • qualifiers (string) = qualifiers of the package

  • subpath (string) = subpath of the package

  • page (integer) = page number of the response

  • page_size (integer) = number of packages in each page

Return a list of packages using a package-url (purl) or a combination of type, namespace, name, version, qualifiers, subpath purl fields. See the purl specification for more details. See example at Query for Package Vulnerabilities section for more details.

/api/packages/bulk_search

Refer to package bulk search section Package Bulk Search

Return a list of packages

/api/vulnerabilities/

  • vulnerability_id (string) = VCID (VulnerableCode Identifier) of the vulnerability

  • page (integer) = page number of the response

  • page_size (integer) = number of vulnerabilities in each page

Return a list of vulnerabilities

/api/cpes

  • cpe (string) = value of the cpe

  • page (integer) = page number of the response

  • page_size (integer) = number of cpes in each page

Return a list of vulnerabilities

/api/cpes/bulk_search

Refer to CPE bulk search section CPE Bulk Search

Return a list of cpes

/api/aliases

  • alias (string) = value of the alias

  • page (integer) = page number of the response

  • page_size (integer) = number of aliases in each page

Return a list of vulnerabilities

Table for other API endpoints

Endpoint

Query Parameters

Expected Output

/api/packages/{id}

  • id (integer) = internal primary id of the package

Return a package with the given id

/api/packages/all

No parameter required

Return a list of all vulnerable packages

/api/vulnerabilities/{id}

  • id (integer) = internal primary id of the vulnerability

Return a vulnerability with the given id

/api/aliases/{id}

  • id (integer) = internal primary id of the alias

Return an alias with the given id

/api/cpes/{id}

  • id = internal primary id of the cpe

Return a cpe with the given id

Miscellaneous

The API is paginated and the default page size is 100. You can change the page size by passing the page_size parameter. You can also change the page number by passing the page parameter.