Snyk API
The Snyk API is available to customers on 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
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 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 . 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
Authorization
To use this API, you must get your token from Snyk. It can be seen on after you register with Snyk and login.
The token should be supplied in an Authorization header with the token, preceded by token:
Otherwise, a 401 "Unauthorized" response will be returned.
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:
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:
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
Take the following upgrade path:
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
actionpackshould be upgraded to at least version5.0.0in order to fix the issue -
Upgrading
actionpackto version5.0.0will causerackto be installed at version2.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:
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:
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:
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.
Detailed example of a payload
project
see:
org
see:
group
see:
issue
see:
Authorization: token API_KEYHTTP/1.1 401 Unauthorized
{ "code": 401, "error": "Not authorised", "message": "Not authorised" }{ "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"}[ "my-project@1.0.0", "actionpack@4.2.5", "rack@1.6.4"][ false, "actionpack@5.0.0", "rack@2.0.1"]HTTP/1.1 500 Internal Server Errorx-error-reference: a45ec9c1-065b-4f7b-baf8-dbd1552ffc9fContent-Type: application/json; charset=utf-8Content-Length: 1848Vary: Accept-EncodingDate: Sun, 10 Sep 2017 06:48:40 GMTimport * 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'];}POST /webhook-handler/snyk123 HTTP/1.1Host: my.app.comX-Snyk-Event: ping/v0X-Snyk-Transport-ID: 998fe884-18a0-45db-8ae0-e379eea3bc0aX-Snyk-Timestamp: 2020-09-25T15:27:53ZX-Hub-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6User-Agent: Snyk-Webhooks/044aaddContent-Type: application/json{ "webhookId": "d3cf26b3-2d77-497b-bce2-23b33cc15362"}POST /webhook-handler/snyk123 HTTP/1.1Host: my.app.comX-Snyk-Event: project_snapshot/v0X-Snyk-Transport-ID: 998fe884-18a0-45db-8ae0-e379eea3bc0aX-Snyk-Timestamp: 2020-09-25T15:27:53ZX-Hub-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6User-Agent: Snyk-Webhooks/044aaddContent-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}"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": { "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": { "name": "ACME Inc.", "id": "a060a49f-636e-480f-9e14-38e773b2a97f"}{ "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" } ] }}```](streamdown:incomplete-link)- Homepage
- https://api.apis.guru/v2/specs/snyk.io/1.0.0.json
- Provider
- snyk.io
- OpenAPI version
- 3.0.0
- Spec (JSON)
- https://api.apis.guru/v2/specs/snyk.io/1.0.0/openapi.json
- Spec (YAML)
- https://api.apis.guru/v2/specs/snyk.io/1.0.0/openapi.yaml
Tools (105)
Extracted live via the executor SDK.
-
auditLogs.getGroupLevelAuditLogs -
auditLogs.getOrganizationLevelAuditLogs -
dependencies.listAllDependencies -
entitlements.getAnOrganizationSEntitlementValue -
entitlements.listAllEntitlements -
groups.addAMemberToAnOrganizationWithinAGroup -
groups.deleteTagFromGroup -
groups.listAllMembersInAGroup -
groups.listAllOrganizationsInAGroup -
groups.listAllRolesInAGroup -
groups.listAllTagsInAGroup -
groups.updateGroupSettings -
groups.viewGroupSettings -
importProjects.getImportJobDetails -
importProjects.importTargets -
integrations.addNewIntegrationAdd new integration for given organization.
-
integrations.cloneAnIntegrationWithSettingsAndCredentialsClone an integration, including all of its settings and credentials from one organization to another organization in the same group. This API supports both brokered and non-brokered integrations.
Use this API for when you want to share a Broker token between several Snyk organizations (integrations).
-
integrations.deleteCredentialsRemoves any credentials set for this integration. If this is a brokered connection the operation will have no effect.
-
integrations.getExistingIntegrationByType -
integrations.list -
integrations.provisionNewBrokerTokenIssue a new and unique provisional broker token for the brokered integration.
Used for zero down-time token rotation with the Snyk Broker. Once provisioned, the token can be used to initialize a new broker client before using the switch API to update the token in use by the integration.
The new provisional token will fail to be created if the integration, or any other integration in the same group, already has one provisioned.
-
integrations.retrieve -
integrations.switchBetweenBrokerTokensSwitch the existing broker token with the provisioned token for this integration and any other in the same group. Only perform this action when you have a Broker client running with the provisioned token. This action will fail if there is no token provisioned for this integration or any integration in the same group.
-
integrations.update -
integrations.updateExistingIntegration-
Update integration's credentials for given organization. Integration must be not brokered
-
Enable or disable brokered integration for given organization. Credentials required for disabling brokered integration
Examples in right section:
-
Set up a broker for an existing integration
-
Update credentials for an existing non-brokered integration
-
Disable broker for an existing integration
-
-
licenses.listAllLicenses -
monitor.monitorDepGraphUse this endpoint to monitor a .
-
organizations.createANewOrganization -
organizations.deletePendingUserProvision -
organizations.getOrgOrgIdNotificationSettings -
organizations.inviteUsers -
organizations.listAllTheOrganizationsAUserBelongsTo -
organizations.listMembers -
organizations.listPendingUserProvisions -
organizations.provisionAUserToTheOrganization -
organizations.removeAMemberFromTheOrganization -
organizations.removeOrganization -
organizations.setNotificationSettings -
organizations.updateAMemberInTheOrganization -
organizations.updateAMemberSRoleInTheOrganization -
organizations.updateOrganizationSettingsSettings that are not provided will not be modified.
-
organizations.viewOrganizationSettings -
projects.activateActivating a project will:
-
Add a repository webhook for supported integrations.
-
Enable pull request tests for new vulnerabilities.
-
Open Fix pull request for newly disclosed vulnerabilities.
-
Enable recurring tests, sending email alerts about newly disclosed vulnerabilities.
-
-
projects.addATagToAProject
-
projects.addIgnore -
projects.applyingAttributesApplies an attribute to the provided project. It is possible to assign multiple values to each attribute, but you can only assign values to one of the predefined attribute categories, using the predefined options for this category. Assigning an attribute requires the caller to be either an Organization Administrator or a Group Administrator. Assigning an attribute will override any existing values that the specific attribute already has set. In order to clear out an attribute value, an empty array can be set.
-
projects.createJiraIssue -
projects.deactivateDeactivating a project will:
-
Disable pull request tests for new vulnerabilities.
-
Disable Fix pull request from being opened for newly disclosed vulnerabilities.
-
Disable recurring tests - email alerts about newly disclosed vulnerabilities will be turned off.
-
If the repository has no other active projects, then remove any webhooks related to the project.
-
-
projects.deleteAProject -
projects.deleteIgnores -
projects.deleteProjectSettingsDeleting project settings will set the project to inherit default settings from its integration.
-
projects.getProjectDependencyGraph -
projects.listAllAggregatedIssues -
projects.listAllIgnoresTemporary ignores include an
expiresattribute, while permanent ignores do not. -
projects.listAllJiraIssues -
projects.listAllProjectIssuePaths -
projects.listAllProjects -
projects.listAllProjectSnapshotAggregatedIssues -
projects.listAllProjectSnapshotIssuePaths -
projects.listAllProjectSnapshots -
projects.listProjectSettings -
projects.moveProjectToADifferentOrganizationNote: when moving a project to a new organization, the historical data used for reporting does not move with it.
-
projects.removeATagFromAProject -
projects.replaceIgnores -
projects.retrieveASingleProject -
projects.retrieveIgnore -
projects.updateAProject -
projects.updateProjectSettings -
reportingApi.getIssueCounts -
reportingApi.getLatestIssueCounts -
reportingApi.getLatestProjectCounts -
reportingApi.getListOfIssues -
reportingApi.getListOfLatestIssues -
reportingApi.getProjectCounts -
reportingApi.getTestCounts -
test.getTestPipPackageNameVersionYou can test
pippackages for issues according to their name and version. -
test.getTestSbtGroupIdArtifactIdVersionYou can test
sbtpackages for issues according to their group ID, artifact ID and version. This is done via the maven endpoint (for Java), since the packages are hosted on maven central or a compatible repository. See "Maven" above for details. -
test.testComposerJsonComposerLockFileYou can test your Composer packages for issues according to their manifest file & lockfile using this action. It takes a JSON object containing a "target"
composer.jsonand acomposer.lock. -
test.testDepGraphUse this endpoint to find issues in a .
-
test.testForIssuesInAPublicGemByNameAndVersionYou can test
rubygemspackages for issues according to their name and version. -
test.testForIssuesInAPublicPackageByGroupIdArtifactIdAndVersionYou can test
mavenpackages for issues according to their : group ID, artifact ID and version. The repository hosting the package may also be customized (see therepositoryquery parameter). -
test.testForIssuesInAPublicPackageByGroupNameAndVersionYou can test
gradlepackages for issues according to their group, name and version. This is done via the maven endpoint (for Java), since the packages are hosted on maven central or a compatible repository. See "Maven" above for details. -
test.testForIssuesInAPublicPackageByNameAndVersionYou can test
npmpackages for issues according to their name and version. -
test.testGemfileLockFileYou can test your rubygems applications for issues according to their lockfile using this action. It takes a JSON object containing a the "target"
Gemfile.lock. -
test.testGopkgTomlGopkgLockFileYou can test your Go dep packages for issues according to their manifest file & lockfile using this action. It takes a JSON object containing a "target"
Gopkg.tomland aGopkg.lock. -
test.testGradleFileYou can test your Gradle packages for issues according to their manifest file using this action. It takes a JSON object containing the "target"
build.gradle. -
test.testMavenFileYou can test your Maven packages for issues according to their manifest file using this action. It takes a JSON object containing a the "target"
pom.xml.Additional manifest files, if they are needed, like parent
pom.xmlfiles, child poms, etc., according the the definitions in the targetpom.xmlfile, should be supplied in theadditionalbody parameter. -
test.testPackageJsonPackageLockJsonFileYou can test your npm packages for issues according to their manifest file & optional lockfile using this action. It takes a JSON object containing a "target"
package.jsonand optionally apackage-lock.json. -
test.testPackageJsonYarnLockFileYou can test your yarn packages for issues according to their manifest file & lockfile using this action. It takes a JSON object containing a "target"
package.jsonand ayarn.lock. -
test.testRequirementsTxtFileYou can test your pip packages for issues according to their manifest file using this action. It takes a JSON object containing a the "target"
requirements.txt. -
test.testSbtFileYou can test your
sbtpackages for issues according to their manifest file using this action. It takes a JSON object containing a the "target"build.sbt. -
test.testVendorJsonFileYou can test your Go vendor packages for issues according to their manifest file using this action. It takes a JSON object containing a "target"
vendor.json. -
users.getMyDetails -
users.getOrganizationNotificationSettings -
users.getProjectNotificationSettings -
users.getUserDetails -
users.modifyOrganizationNotificationSettings -
users.modifyProjectNotificationSettings -
webhooks.createAWebhook -
webhooks.deleteAWebhook -
webhooks.listWebhooks -
webhooks.pingAWebhook -
webhooks.retrieveAWebhook -
openapi.previewSpecPreview an OpenAPI document before adding it as a source
-
openapi.addSourceAdd an OpenAPI source and register its operations as tools