Snyk API

The Snyk API is available to customers on Business and Enterprise plans and allows you to programatically integrate with Snyk.

REST API

We are in the process of building a new, improved API (https://api.snyk.io/rest) built using the OpenAPI and JSON API standards. We welcome you to try it out as we shape and release endpoints until it, ultimately, becomes a full replacement for our current API.

Looking for our REST API docs? Please head over to https://apidocs.snyk.io

API vs CLI vs Snyk integration

The API detailed below has the ability to test a package for issues, as they are defined by Snyk. It is important to note that for many package managers, using this API will be less accurate than running the Snyk CLI as part of your build pipe, or just using it locally on your package. The reason for this is that more than one package version fit the requirements given in manifest files. Running the CLI locally tests the actual deployed code, and has an accurate snapshot of the dependency versions in use, while the API can only infer it, with inferior accuracy. It should be noted that the Snyk CLI has the ability to output machine-readable JSON output (with the --json flag to snyk test).

A third option, is to allow Snyk access to your development flow via the existing Snyk integrations. The advantage to this approach is having Snyk monitor every new pull request, and suggest fixes by opening new pull requests. This can be achieved either by integrating Snyk directly to your source code management (SCM) tool, or via a broker to allow greater security and auditability.

If those are not viable options, this API is your best choice.

API url

The base URL for all API endpoints is https://api.snyk.io/api/v1/

Authorization

To use this API, you must get your token from Snyk. It can be seen on https://snyk.io/account/ after you register with Snyk and login.

The token should be supplied in an Authorization header with the token, preceded by token:

Authorization: token API_KEY

Otherwise, a 401 “Unauthorized” response will be returned.

HTTP/1.1 401 Unauthorized

        {
            "code": 401,
            "error": "Not authorised",
            "message": "Not authorised"
        }

Overview and entities

The API is a REST API. It has the following entities:

Test result

The test result is the object returned from the API giving the results of testing a package for issues. It has the following fields:

Issue

An issue is either a vulnerability or a license issue, according to the organization’s policy. It has the following fields:

Vulnerability

A vulnerability in a package. In addition to all the fields present in an issue, a vulnerability also has these fields:

Patch

A patch is an object like this one:

{
  "urls": [
    "https://snyk-patches.s3.amazonaws.com/npm/backbone/20110701/backbone_20110701_0_0_0cdc525961d3fa98e810ffae6bcc8e3838e36d93.patch"
  ],
  "version": "<0.5.0 >=0.3.3",
  "modificationTime": "2015-11-06T02:09:36.180Z",
  "comments": [
    "https://github.com/jashkenas/backbone/commit/0cdc525961d3fa98e810ffae6bcc8e3838e36d93.patch"
  ],
  "id": "patch:npm:backbone:20110701:0"
}

From and upgrade paths

Both from and upgrade paths are arrays, where each item within the array is a package name@version.

Take the following from path:

[
  "my-project@1.0.0",
  "actionpack@4.2.5",
  "rack@1.6.4"
]

Assuming this was returned as a result of a test, then we know:

• The package that was tested was my-project@1.0.0

• The dependency with an issue was included in the tested package via the direct dependency actionpack@4.2.5

• The dependency with an issue was rack@1.6.4

Take the following upgrade path:

[
  false,
  "actionpack@5.0.0",
  "rack@2.0.1"
]

Assuming this was returned as a result of a test, then we know:

• The package that was tested is not upgradable (false)

• The direct dependency actionpack should be upgraded to at least version 5.0.0 in order to fix the issue

• Upgrading actionpack to version 5.0.0 will cause rack to be installed at version 2.0.1

If the upgrade path comes back as an empty array ([]) then this means that there is no upgrade path available which would fix the issue.

License issue

A license issue has no additional fields other than the ones in “Issue”.

Snyk organization

The organization in Snyk this request is applicable to. The organization determines the access rights, licenses policy and is the unit of billing for private projects.

A Snyk organization has these fields:

Errors

This is a beta release of this API. Therefore, despite our efforts, errors might occur. In the unlikely event of such an error, it will have the following structure as JSON in the body:

The error reference will also be supplied in the x-error-reference header in the server reply.

Example response:

HTTP/1.1 500 Internal Server Error
x-error-reference: a45ec9c1-065b-4f7b-baf8-dbd1552ffc9f
Content-Type: application/json; charset=utf-8
Content-Length: 1848
Vary: Accept-Encoding
Date: Sun, 10 Sep 2017 06:48:40 GMT

Rate Limiting

To ensure resilience against increasing request rates, we are starting to introduce rate-limiting. We are monitoring the rate-limiting system to ensure minimal impact on users while ensuring system stability. Current limit is up to 2000 requests per minute, per user. This limit is above industry standards, and is subject to change. As such, we recommend calls to the API are throttled regardless of the current limit. All requests above the limit will get a response with status code 429 - Too many requests until requests stop for the duration of the rate-limiting interval (currently a minute).

Consuming Webhooks

Webhooks are delivered with a Content-Type of application/json, with the event payload as JSON in the request body. We also send the following headers:

• X-Snyk-Event - the name of the event

• X-Snyk-Transport-ID - a GUID to identify this delivery

• X-Snyk-Timestamp - an ISO 8601 timestamp for when the event occurred, for example: 2020-09-25T15:27:53Z

• X-Hub-Signature - the HMAC hex digest of the request body, used to secure your webhooks and ensure the request did indeed come from Snyk

• User-Agent - identifies the origin of the request, for example: Snyk-Webhooks/XXX

After your server is configured to receive payloads, it listens for any payload sent to the endpoint you configured. For security reasons, you should limit requests to those coming from Snyk.

Validating payloads

All transports sent to your webhooks have a X-Hub-Signature header, which contains the hash signature for the transport. The signature is a HMAC hexdigest of the request body, generated using sha256 and your secret as the HMAC key.

You could use a function in Node.JS such as the following to validate these signatures on incoming requests from Snyk:

import * as crypto from 'crypto';

function verifySignature(request, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const buffer = JSON.stringify(request.body);
  hmac.update(buffer, 'utf8');

  const signature = `sha256=${hmac.digest('hex')}`;

  return signature === request.headers['x-hub-signature'];
}

Payload versioning

Payloads may evolve over time, and so are versioned. Payload versions are supplied as a suffix to the X-Snyk-Event header. For example, project_snapshot/v0 indicates that the payload is v0 of the project_snapshot event.

Version numbers only increment when a breaking change is made; for example, removing a field that used to exist, or changing the name of a field. Version numbers do not increment when making an additive change, such as adding a new field that never existed before.

Note: During the BETA phase, the structure of webhook payloads may change at any time, so we recommend you check the payload version.

Event types

While consuming a webhook event, X-Snyk-Event header must be checked, as an end-point may receive multiple event types.

ping

The ping event happens after a new webhook is created, and can also be manually triggered using the ping webhook API. This is useful to test that your webhook receives data from Snyk correctly.

The ping event makes the following request:

POST /webhook-handler/snyk123 HTTP/1.1
Host: my.app.com
X-Snyk-Event: ping/v0
X-Snyk-Transport-ID: 998fe884-18a0-45db-8ae0-e379eea3bc0a
X-Snyk-Timestamp: 2020-09-25T15:27:53Z
X-Hub-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6
User-Agent: Snyk-Webhooks/044aadd
Content-Type: application/json
{
  "webhookId": "d3cf26b3-2d77-497b-bce2-23b33cc15362"
}

project_snapshot

This event is triggered every time an existing project is tested and a new snapshot is created. It is triggered on every test of a project, whether or not there are new issues. This event is not triggered when a new project is created or imported. Currently supported targets/scan types are Open Source and container.

POST /webhook-handler/snyk123 HTTP/1.1
Host: my.app.com
X-Snyk-Event: project_snapshot/v0
X-Snyk-Transport-ID: 998fe884-18a0-45db-8ae0-e379eea3bc0a
X-Snyk-Timestamp: 2020-09-25T15:27:53Z
X-Hub-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6
User-Agent: Snyk-Webhooks/044aadd
Content-Type: application/json
{
  "project": { ... }, // project object matching API responses
  "org": { ... }, // organization object matching API responses
  "group": { ... }, // group object matching API responses
  "newIssues": [], // array of issues object matching API responses
  "removedIssues": [], // array of issues object matching API responses
}

Detailed example of a payload

project

see: https://snyk.docs.apiary.io/#reference/projects

"project": {
  "name": "snyk/goof",
  "id": "af137b96-6966-46c1-826b-2e79ac49bbd9",
  "created": "2018-10-29T09:50:54.014Z",
  "origin": "github",
  "type": "maven",
  "readOnly": false,
  "testFrequency": "daily",
  "totalDependencies": 42,
  "issueCountsBySeverity": {
    "low": 13,
    "medium": 8,
    "high": 4,
    "critical": 5
  },
  "imageId": "sha256:caf27325b298a6730837023a8a342699c8b7b388b8d878966b064a1320043019",
  "imageTag": "latest",
  "imageBaseImage": "alpine:3",
  "imagePlatform": "linux/arm64",
  "imageCluster": "Production",
  "hostname": null,
  "remoteRepoUrl": "https://github.com/snyk/goof.git",
  "lastTestedDate": "2019-02-05T08:54:07.704Z",
  "browseUrl": "https://app.snyk.io/org/4a18d42f-0706-4ad0-b127-24078731fbed/project/af137b96-6966-46c1-826b-2e79ac49bbd9",
  "importingUser": {
    "id": "e713cf94-bb02-4ea0-89d9-613cce0caed2",
    "name": "example-user@snyk.io",
    "username": "exampleUser",
    "email": "example-user@snyk.io"
  },
  "isMonitored": false,
  "branch": null,
  "targetReference": null,
  "tags": [
    {
      "key": "example-tag-key",
      "value": "example-tag-value"
    }
  ],
  "attributes": {
    "criticality": [
      "high"
    ],
    "environment": [
      "backend"
    ],
    "lifecycle": [
      "development"
    ]
  },
  "remediation": {
    "upgrade": {},
    "patch": {},
    "pin": {}
  }
}

org

see: https://snyk.docs.apiary.io/#reference/organizations

"org": {
  "name": "My Org",
  "id": "a04d9cbd-ae6e-44af-b573-0556b0ad4bd2",
  "slug": "my-org",
  "url": "https://api.snyk.io/org/my-org",
  "created": "2020-11-18T10:39:00.983Z"
}

group

see: https://snyk.docs.apiary.io/#reference/groups

"group": {
  "name": "ACME Inc.",
   "id": "a060a49f-636e-480f-9e14-38e773b2a97f"
}

issue

see: https://snyk.docs.apiary.io/#reference/users/user-organization-notification-settings/list-all-aggregated-issues

{
  "id": "npm:ms:20170412",
  "issueType": "vuln",
  "pkgName": "ms",
  "pkgVersions": [
    "1.0.0"
  ],
  "issueData": {
    "id": "npm:ms:20170412",
    "title": "Regular Expression Denial of Service (ReDoS)",
    "severity": "low",
    "url": "https://snyk.io/vuln/npm:ms:20170412",
    "description": "Lorem ipsum",
    "identifiers": {
      "CVE": [],
      "CWE": [
        "CWE-400"
      ],
      "ALTERNATIVE": [
        "SNYK-JS-MS-10509"
      ]
    },
    "credit": [
      "Snyk Security Research Team"
    ],
    "exploitMaturity": "no-known-exploit",
    "semver": {
      "vulnerable": [
        ">=0.7.1 <2.0.0"
      ]
    },
    "publicationTime": "2017-05-15T06:02:45Z",
    "disclosureTime": "2017-04-11T21:00:00Z",
    "CVSSv3": "CVSS:3.0/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:N/A:L",
    "cvssScore": 3.7,
    "language": "js",
    "patches": [
      {
        "id": "patch:npm:ms:20170412:2",
        "urls": [
          "https://snyk-patches.s3.amazonaws.com/npm/ms/20170412/ms_071.patch"
        ],
        "version": "=0.7.1",
        "comments": [],
        "modificationTime": "2019-12-03T11:40:45.866206Z"
      }
    ],
    "nearestFixedInVersion": "2.0.0"
  },
  "isPatched": false,
  "isIgnored": false,
  "fixInfo": {
    "isUpgradable": false,
    "isPinnable": false,
    "isPatchable": true,
    "nearestFixedInVersion": "2.0.0"
  },
  "priority": {
    "score": 399,
    "factors": [
      {
        "name": "isFixable",
        "description": "Has a fix available"
      },
      {
        "name": "cvssScore",
        "description": "CVSS 3.7"
      }
    ]
  }
}

Use this page to mock Snyk API in your testing and development.

Run our mock API sample using the open source WireMock library, or in the free edition of WireMock Cloud. You'll have a working API server simulating the behavior of Snyk API, which will allow you to keep building and testing even if the actual API you isn't currently available.