V3 API Overview

Overview

VulnCheck API endpoints are optimized for programmatic access and deliver JSON machine-readable data.

VulnCheck indices can be accessed using either the backup endpoint, which provides a complete copy of the index for download, or the index endpoint, which provides a paginated list of documents and can be used to query individual records.

A list of the 'index' and 'backup' API endpoints that you have access to, can be found in the VulnCheck API Sandbox located in the VulnCheck dashboard.

First Steps

1. Sign up for a VulnCheck Account. This will give you immediate access to our community resources.
2. Log into the VulnCheck Dashboard.
3. Click on the API Sandbox to explore the VulnCheck indexes that you have permission to access.
4. Generate a token for programmatic API access.

API Details

All API methods use https://api.vulncheck.com/ for the base URL.

Error Handling

The VulnCheck API uses standard HTTP status codes to indicate the success or failure of requests. Most client errors return a 400 status code, particularly for requests to indexes that don't exist or for invalid parameters.

All error responses follow a consistent JSON structure:

{
  "error": true,
  "errors": [
    "failed to query requested index"
  ]
}

Common Error Scenarios:

• 400 Bad Request: Invalid parameters, malformed requests, or requests for non-existent indexes
• 401 Unauthorized: Invalid or missing authentication token
• 402 Payment Required: Subscription required to view requested data
• 403 Forbidden: Valid authentication but insufficient permissions for the requested resource
• 429 Too Many Requests: Rate limiting exceeded
• 500 Internal Server Error: Server-side errors

Rate Limiting

Community user API requests are limited to 1,000 requests per minute. When this limit is exceeded, the API will return a 429 "Too Many Requests" status code.

To avoid rate limiting, consider:

• Implementing exponential backoff in your application
• Caching API responses when appropriate
• Upgrading to a paid plan for higher rate limits

API Example Request

curl --request GET \
    --url https://api.vulncheck.com/v3/backup/vulncheck-kev \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer insert_token_here'

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"

    vulncheck "github.com/vulncheck-oss/sdk-go-v2/v2"
)

func main() {
    configuration := vulncheck.NewConfiguration()
    configuration.Scheme = "https"
    configuration.Host = "api.vulncheck.com"

    client := vulncheck.NewAPIClient(configuration)

    token := os.Getenv("VULNCHECK_API_TOKEN")
    auth := context.WithValue(
        context.Background(),
        vulncheck.ContextAPIKeys,
        map[string]vulncheck.APIKey{
            "Bearer": {Key: token},
        },
    )
    resp, httpRes, err := client.EndpointsAPI.BackupIndexGet(auth, "vulncheck-kev").Execute()

    if err != nil || httpRes.StatusCode != 200 {
        log.Fatal(err)
    }

    prettyJSON, err := json.MarshalIndent(resp.Data, "", "  ")
    if err != nil {
        log.Fatalf("Failed to generate JSON: %v", err)
        return
    }

    fmt.Println(string(prettyJSON))
}

import vulncheck_sdk

configuration = vulncheck_sdk.Configuration(host="https://api.vulncheck.com/v3")
configuration.api_key["Bearer"] = "insert_token_here"

with vulncheck_sdk.ApiClient(configuration) as api_client:
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    api_response = endpoints_client.backup_index_get("vulncheck-kev")

    print(api_response.data[0].url)

vulncheck backup download vulncheck-kev

API Date Format

VulnCheck utilizes RFC3339Nano formatted dates across our datasets. This format has the peculiarity of removing trailing zeros from the seconds field, leading to slightly inconsistent timestamps. For example, both of the following are valid RFC3339Nano timestamps:

2024-02-14T16:15:00Z
2024-02-23T10:38:41.361178Z

Although they appear inconsistent, they are both valid and parsable RFC3339Nano date formats.