The Semgrep API is the programmatic interface to the Semgrep AppSec Platform, letting you list deployments, pull findings, manage projects, and administer tokens without clicking through the web app. If you run static analysis at any scale, the API is how you move results into your own dashboards, ticketing, and metrics rather than living inside Semgrep's UI. This guide covers how authentication works, what the API is good for, and the operational details that trip teams up.
Two different Semgrep surfaces
It helps to separate two things that both carry the Semgrep name. The Semgrep CLI is the open-source scanner you run locally or in CI. The Semgrep AppSec Platform (formerly Semgrep App, at semgrep.dev) is the hosted service that stores findings, manages rules, and provides the API. The API talks to the platform, not to the CLI directly. You typically scan with the CLI in CI, the results flow to the platform, and then you query the API to get them back out programmatically.
Authentication: tokens and tiers
Access to the platform starts with a login token. Running semgrep login opens an OAuth flow with the platform and writes an authentication token to ~/.semgrep/settings.yml. That token is what semgrep ci uses to upload results.
For the web API itself, you provision an API token in the platform settings and send it as a bearer token. Note that programmatic API access generally requires a Team or Enterprise tier account rather than the free tier, so confirm your plan before building against it.
curl -s https://semgrep.dev/api/v1/deployments \
-H "Authorization: Bearer $SEMGREP_API_TOKEN"
That call lists the deployments your token can see. A deployment is the top-level container for your organization's projects and findings, and its identifier (the deployment slug) is what most other endpoints hang off of.
Pulling findings programmatically
The most common reason to touch the API is to extract findings so you can route them into your own systems. Once you have the deployment slug, you can list projects and their findings:
# List projects in a deployment
curl -s "https://semgrep.dev/api/v1/deployments/$SLUG/projects" \
-H "Authorization: Bearer $SEMGREP_API_TOKEN"
# Pull findings for the deployment
curl -s "https://semgrep.dev/api/v1/deployments/$SLUG/findings" \
-H "Authorization: Bearer $SEMGREP_API_TOKEN"
Findings come back as JSON you can filter by severity, status, or rule, then forward to a SIEM, a ticket tracker, or a metrics pipeline. This is exactly how integrations with compliance platforms and security dashboards pull Semgrep data in without a human exporting CSVs.
How scans report back to the platform
Understanding the reporting protocol helps you debug CI issues. The semgrep ci command uses a multi-phase exchange with the platform: it opens a scan by sending project metadata (git repository, branch, commit, CI environment), runs the scan, and then uploads results and completes the scan. This is why the platform can show a partial or errored scan in the UI even when the CLI run died midway. Separately, the scanner sends usage metrics to metrics.semgrep.dev after a scan; if you operate in a locked-down network, allowlist or explicitly disable that as your policy requires.
Managing tokens at scale
Tokens are credentials, so treat them like secrets. A few operational notes:
- Scope by type. The platform distinguishes token types (Admin, CI, Member, CLI). Use a CI-scoped token in pipelines, not an Admin token, so a leaked CI secret cannot administer your org.
- Rotate and revoke. The API supports bulk token deletion, with dedicated endpoints per token type, which makes cleanup after a suspected leak or an employee departure practical to automate.
- Store them properly. Keep tokens in your CI secret store, never in the repository. This is precisely the kind of leak a secrets scanner is built to catch, and a broader software composition and pipeline security program should watch for it.
Where the Semgrep API fits
The API turns Semgrep from a tool developers run into a data source your security program consumes. That is the right way to think about most scanners: the scan is only useful if its output lands somewhere findings get triaged and tracked. If you are assembling a pipeline where static analysis feeds a central findings store alongside SCA and other scanners, the Semgrep API is the connector that makes it happen. Our academy has patterns for consolidating multi-tool findings so they do not become noise.
FAQ
What can the Semgrep API do?
It lets you list deployments and projects, pull findings, and administer API tokens programmatically. Teams use it to export findings into SIEMs, ticketing systems, dashboards, and compliance platforms rather than working inside Semgrep's web UI.
How do I authenticate to the Semgrep API?
Provision an API token in the platform settings and send it as a bearer token in the Authorization header. Separately, semgrep login writes a login token to ~/.semgrep/settings.yml that semgrep ci uses to upload scan results.
Do I need a paid plan for the Semgrep API?
Programmatic API access generally requires a Team or Enterprise tier account, so verify your plan level before building an integration against it.
How should I manage Semgrep API tokens securely?
Use type-scoped tokens (a CI token in pipelines, not an Admin token), store them in your CI secret manager rather than the repo, and rotate or bulk-revoke them via the API after any suspected leak or personnel change.