A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Snyk API is how an app or AI agent works with a Snyk account: listing the projects in an organization, reading the security issues a scan found, generating a software bill of materials for a project, and searching the audit log of who did what. Access is granted through an API token, which carries the full access of its account, or an OAuth 2.0 app with a granular set of scopes, and an agent is limited to the organizations and groups its token can reach. Versions are pinned by date, and Snyk can also push an event to a webhook when a project is tested.
How an app or AI agent connects to Snyk determines what it can reach. There are several routes, each governed by the token behind it and the permissions or scopes that token carries.
The REST API answers at https://api.snyk.io/rest, with regional hosts for the US, EU, and AU. Every request pins a dated version through the version query parameter, and responses follow the JSON:API format.
Snyk publishes two first-party Model Context Protocol servers. The Snyk CLI runs a local MCP server with snyk mcp -t stdio, exposing its scanning to MCP-enabled tools, and the Snyk API and Web MCP server brings onboarding targets and triaging vulnerabilities into AI development tools through natural language. Both were in preview as of the verification date.
Webhooks deliver chosen events to a receiver URL over HTTPS. Each delivery carries an X-Hub-Signature header, an HMAC of the body keyed by a secret only the receiver knows, so the receiver can confirm it came from Snyk.
The older V1 API answers at https://api.snyk.io/v1 and still serves some functionality the REST API has not yet replaced, such as listing a project's dependencies. Snyk recommends the REST API where an equivalent endpoint exists.
A personal API token is sent in an Authorization: token header. It carries the full access of the account it belongs to, so it reaches every organization and project that account can see.
A service account is a machine identity scoped to an organization or a group, with its own token and a fixed role. It is the recommended credential for automation, because it is not tied to a person who might leave.
A Snyk App acts through OAuth 2.0 with a granular set of scopes, where org.read is always required, and its access token is sent in an Authorization: bearer header. Enterprise service accounts can also use the OAuth 2.0 client credentials flow for short-lived, refreshable tokens.
The Snyk API is split into areas an agent can act on, such as organizations, projects, issues, targets, and software bills of materials. Each area has its own methods and its own permissions, and some grant access to far more than others.
List the organizations a token can reach, read and update an organization's settings, and manage its memberships.
List groups, read a single group, list the organizations inside a group, and manage group memberships.
List the projects in an organization, read a single project, update its settings, and delete a project.
List the security issues found in an organization or group and read a single issue.
List the targets, the scanned repositories or images, that projects belong to, read a single target, and delete one.
Start a software bill of materials test, read its status and results, and list a project's dependencies.
Generate a software bill of materials document for a project, listing every component the scan found.
Search the audit log of an organization or a group for the actions taken in it.
Create, list, read, update, and delete the machine identities that automation uses to call Snyk at the organization or group level.
Create, read, edit, and delete collections of projects, and add or remove the projects inside them.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
OrganizationsList the organizations a token can reach, read and update an organization's settings, and manage its memberships.4 | ||||||
| GET | /orgs | List the organizations the authenticated token can access. | read | org.read | Current | |
OAuth scope org.read is mandatory and must always be requested. An API token reaches whatever organizations its account can see. Acts onorganization Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /orgs/{org_id} | Update an organization's information and settings. | write | org.edit | Current | |
OAuth scope org.edit, which covers editing organization information and settings. Acts onorganization Permission (capability) org.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/memberships | List the memberships of an organization. | read | org.read | Current | |
OAuth scope org.read. Memberships list the people who belong to the organization. Acts onmembership Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org_id}/memberships | Add a member to an organization. | write | org.edit | Current | |
OAuth scope org.edit, which governs changes to organization settings and membership. Acts onmembership Permission (capability) org.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsList groups, read a single group, list the organizations inside a group, and manage group memberships.2 | ||||||
| GET | /groups | List the groups the authenticated token can access. | read | org.read | Current | |
A group sits above organizations. Group endpoints are read with the same org.read scope and a token whose account has group access. Acts ongroup Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /groups/{group_id}/orgs | List the organizations that belong to a group. | read | org.read | Current | |
OAuth scope org.read. Returns every organization the token can see inside the group. Acts onorganization Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList the projects in an organization, read a single project, update its settings, and delete a project.4 | ||||||
| GET | /orgs/{org_id}/projects | List the projects in an organization. | read | org.project.read | Current | |
OAuth scope org.project.read, which also covers viewing the organization's targets. Acts onproject Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/projects/{project_id} | Get a single project by its ID. | read | org.project.read | Current | |
OAuth scope org.project.read. Acts onproject Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /orgs/{org_id}/projects/{project_id} | Update a project's information and settings. | write | org.project.edit | Current | |
OAuth scope org.project.edit. Activating or deactivating a project instead needs org.project.status. Acts onproject Permission (capability) org.project.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /orgs/{org_id}/projects/{project_id} | Permanently delete a project. | write | org.project.delete | Current | |
OAuth scope org.project.delete, which permanently removes projects and organization targets. This cannot be undone. Acts onproject Permission (capability) org.project.deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IssuesList the security issues found in an organization or group and read a single issue.3 | ||||||
| GET | /orgs/{org_id}/issues | List the security issues found across an organization. | read | org.project.read | Current | |
Reading issue and scan data uses org.project.read, the same scope that lists projects. Acts onissue Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/issues/{issue_id} | Get a single issue by its ID. | read | org.project.read | Current | |
OAuth scope org.project.read. An issue describes a found vulnerability and its severity. Acts onissue Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /groups/{group_id}/issues | List the security issues found across a group. | read | org.project.read | Current | |
OAuth scope org.project.read, with a token whose account can see the group. Acts onissue Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TargetsList the targets, the scanned repositories or images, that projects belong to, read a single target, and delete one.3 | ||||||
| GET | /orgs/{org_id}/targets | List the targets in an organization, the scanned repositories or images projects belong to. | read | org.project.read | Current | |
Viewing organization targets is part of the org.project.read scope. Acts ontarget Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/targets/{target_id} | Get a single target by its ID. | read | org.project.read | Current | |
OAuth scope org.project.read. Acts ontarget Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /orgs/{org_id}/targets/{target_id} | Delete a target and the projects under it. | write | org.project.delete | Current | |
Removing a target uses org.project.delete, which permanently removes the target and the projects within it. Acts ontarget Permission (capability) org.project.deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tests & dependenciesStart a software bill of materials test, read its status and results, and list a project's dependencies.4 | ||||||
| POST | /orgs/{org_id}/sbom_tests | Start a test of a supplied software bill of materials for known issues. | write | org.project.test | Current | |
OAuth scope org.project.test. This endpoint is beta. It starts an asynchronous job whose status and results are fetched separately. Acts ontest Permission (capability) org.project.testVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/sbom_tests/{job_id} | Get the status of a software bill of materials test job. | read | org.project.read | Current | |
OAuth scope org.project.read. This endpoint is beta. Acts ontest Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orgs/{org_id}/sbom_tests/{job_id}/results | Get the issues found by a completed software bill of materials test. | read | org.project.read | Current | |
OAuth scope org.project.read. This endpoint is beta. Acts ontest Permission (capability) org.project.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /org/{org_id}/project/{project_id}/dependencies | List all the dependencies of a project. | read | org.project.snapshot.read | Current | |
This is a V1 endpoint. Viewing scanned dependency data maps to the org.project.snapshot.read scope. Acts ondependency Permission (capability) org.project.snapshot.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SBOMGenerate a software bill of materials document for a project, listing every component the scan found.1 | ||||||
| GET | /orgs/{org_id}/projects/{project_id}/sbom | Generate a software bill of materials document for a project. | read | org.project.snapshot.read | Current | |
The document lists every component a scan found, so it maps to org.project.snapshot.read. It can be returned in CycloneDX or SPDX format. Acts onsbom Permission (capability) org.project.snapshot.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Audit logsSearch the audit log of an organization or a group for the actions taken in it.2 | ||||||
| GET | /orgs/{org_id}/audit_logs/search | Search the audit log of an organization for the actions taken in it. | read | org.read | Current | |
Reading the audit log uses org.read. The log records who took which action and when. Acts onaudit log Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /groups/{group_id}/audit_logs/search | Search the audit log of a group for the actions taken in it. | read | org.read | Current | |
OAuth scope org.read, with a token whose account can see the group. Acts onaudit log Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Service accountsCreate, list, read, update, and delete the machine identities that automation uses to call Snyk at the organization or group level.3 | ||||||
| GET | /orgs/{org_id}/service_accounts | List the service accounts of an organization. | read | org.read | Current | |
A service account is a machine identity used by automation. Listing them reads organization settings, governed by org.read. Acts onservice account Permission (capability) org.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org_id}/service_accounts | Create a service account for an organization. | write | org.edit | Current | |
Creating a service account changes organization settings, governed by org.edit. It mints a long-lived credential that can call Snyk on its own. Acts onservice account Permission (capability) org.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /orgs/{org_id}/service_accounts/{serviceaccount_id} | Delete a service account from an organization. | write | org.edit | Current | |
OAuth scope org.edit. Deleting a service account revokes a machine credential. Acts onservice account Permission (capability) org.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CollectionsCreate, read, edit, and delete collections of projects, and add or remove the projects inside them.4 | ||||||
| GET | /orgs/{org_id}/collections | List the project collections in an organization. | read | org.collection.read | Current | |
OAuth scope org.collection.read. A collection is a saved grouping of projects. Acts oncollection Permission (capability) org.collection.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org_id}/collections | Create a project collection in an organization. | write | org.collection.create | Current | |
OAuth scope org.collection.create. Acts oncollection Permission (capability) org.collection.createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orgs/{org_id}/collections/{collection_id}/relationships/projects | Add projects to a collection. | write | org.collection.edit | Current | |
OAuth scope org.collection.edit, which adds and removes projects from collections. Acts oncollection Permission (capability) org.collection.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /orgs/{org_id}/collections/{collection_id} | Delete a project collection. | write | org.collection.delete | Current | |
OAuth scope org.collection.delete. The projects in the collection are not deleted, only the grouping. Acts oncollection Permission (capability) org.collection.deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Snyk can notify an app or AI agent when something happens, such as a project being tested, instead of the app repeatedly asking. Snyk posts the event payload to a webhook URL that has been registered, and signs each delivery so the receiver can confirm it came from Snyk.
| Event | What it signals | Triggered by |
|---|---|---|
ping | Fires after a new webhook is created, and can also be triggered manually through the ping webhook API, to confirm the receiver is reachable. | In-app only |
project_snapshot | Fires on every test of a project, whether or not new issues were found, currently for open source and container scans. The payload carries the new snapshot of the project's issues. | In-app only |
Snyk limits how fast an app or AI agent can call, through a per-key request quota measured each minute, and returns cursor-based pages for any list that can grow long.
Snyk caps calls at 1,620 requests per minute per API key. The limit is counted on the key, not per endpoint, so all of a token's calls share the same per-minute budget. Going over returns 429 Too Many Requests, and the fix is to slow the request rate and spread calls below the ceiling.
List endpoints use cursor-based pagination through opaque starting_after and ending_before parameters, with a limit parameter that sets the page size. A response includes links to the next and previous pages, and the next link should be followed rather than built by hand. There is no offset or page-number scheme.
Requests and responses are JSON in the JSON:API format. An SBOM document can be requested in CycloneDX or SPDX format and lists a project's full component tree, so it can be large for a project with many dependencies. Snyk does not document a single fixed payload size limit across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, such as a missing required parameter or an invalid value. The body is a JSON:API error object with a detail field explaining the problem. | Read the detail and source fields in the error, correct the named parameter, and resend. |
| 401 | Unauthorized | Authentication is missing or invalid, such as a missing Authorization header or an expired or revoked token. | Send a valid token in the Authorization header, as token for an API token or bearer for an OAuth access token. |
| 403 | Forbidden | The token is valid but lacks the permission or scope for the action, or cannot reach the organization or group named in the path. | Grant the missing scope, such as org.project.read, or use a token whose account has access to the resource. |
| 404 | Not Found | The resource does not exist, or the token cannot see it. A wrong org_id, project_id, or target_id returns 404. | Confirm the IDs in the path are correct and the token has access to them. |
| 429 | Too Many Requests | The per-key rate limit was exceeded. Snyk allows 1,620 requests per minute per API key. | Slow the request rate and retry after a short wait, spreading calls below the per-minute ceiling. |
Snyk versions its REST API by date. Each version is a string like 2024-10-15, and Snyk recommends pinning that version unless an earlier one is needed for a specific reason.
Snyk recommends pinning 2024-10-15 as the version date unless an earlier version is needed for a specific reason. Versions are dated strings in YYYY-MM-DD form, each generally available, beta, or experimental. A generally available version is supported for at least six months after the next one ships, and a deprecated endpoint returns a Sunset header naming the date it stops working.
Announced on 17 September 2024, this change moved Snyk to one API specification per version date, minting a new version only on a breaking change. New beta versions are pinned by date alone, such as 2024-08-02 rather than 2024-08-02~beta, and a closed-beta stability level replaced experimental for new endpoints after 17 October 2024. The version string here marks the announcement date, not a new dated API version.
2022-04-06 was the first generally available dated version of the Snyk REST API, establishing the date-based versioning model where each endpoint carries its own version contract and support lifecycle independent of the others. It set the JSON:API response format and the cursor-based pagination the API still uses.
An integration pins a date and moves up on a schedule that suits it, with each generally available version supported for at least six months after the next one ships.
Snyk API changelog ↗Bollard AI sits between a team's AI agents and Snyk. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.