API and Development
Ossprey's public REST API for triggering scans, retrieving results, and integrating programmatically.
Overview
Ossprey exposes a public REST API for triggering scans, retrieving scan results, and integrating Ossprey into your own tooling. The API is the same surface used by the dashboard and CI integrations, so anything you can do in the UI you can do via the API.
The base URL is https://api.ossprey.com. The full machine-readable OpenAPI definition drives the interactive API Reference on this site — browse it there to try any endpoint against your own key.
Authentication
All endpoints (except /health and the alert-verification callback) require an API key passed via the x-api-key header:
curl https://api.ossprey.com/public/v1/scans -H "x-api-key: $OSSPREY_API_KEY"Keys look like ospy_ followed by 64 hex characters. Create them at dashboard.ossprey.com (Account → API Keys) — the key is shown once, at creation, and requires an expiry date of at most 2 years. See Security & API Keys for storage and rotation best practices.
Endpoints at a glance
| Method | Path | Purpose |
|---|---|---|
GET | /health | Service health check (no auth). |
POST | /public/v1/scans | Submit an SBOM for scanning. |
GET | /public/v1/scans | List your SBOMs with the latest scan status. |
GET | /public/v1/scans/status | Poll a queued/running scan (sbom_id + scan_id). |
GET | /public/v1/scans/{sbom_id} | Get one SBOM with all scans, vulnerabilities and findings. |
DELETE | /public/v1/scans/{sbom_id} | Delete an SBOM and its scan records. |
POST | /public/v1/tools/sbom | Generate an SBOM from a Package URL (GitHub repos). |
GET | /public/v1/malware | Threat-intelligence feed of malware detected in the package cache. |
POST | /public/v1/malware/check | Check a batch of package URLs against the known-malware knowledge base. Cache-only — it never queues a scan. |
POST | /public/v1/pulls | Ingest observed package pulls from a registry collector — see Artifact Caches. |
POST | /public/v1/mcp | Model Context Protocol server (JSON-RPC over Streamable HTTP). |
POST | /public/v1/alerts/verify | Confirm an alert email address via a one-time token (no auth). |
Errors and quotas
Failures return a standard envelope:
{
"status": "FAILED",
"error": "Human-readable message",
"message": "Human-readable message"
}Scan submissions are subject to daily and monthly package quotas set by your plan. Accepted submissions include X-Quota-Limit-Daily, X-Quota-Used-Daily, X-Quota-Resets-At-Daily response headers (and monthly equivalents); exceeding a quota returns 429. Packages Ossprey can resolve from cache or by reputation aren't charged against your quota. Ingesting pulls via /public/v1/pulls doesn't consume quota at all, and neither does /public/v1/malware/check — it reads the knowledge base only and never queues a scan (up to 100 package URLs per request).
Common use cases
- Submitting an SBOM or dependency manifest for scanning — see the API Quickstart
- Polling scan status and fetching results
- Listing SBOMs, scans, and detected findings
- Consuming the malware feed for your own threat intelligence
- Giving AI agents access to scans via the MCP server
- Integrating Ossprey into custom CI/CD pipelines beyond the standard GitHub Action
What's new
ChangelogOssprey ships updates regularly. For the latest features, improvements, and fixes, including changes that affect the API, see the changelog at https://dashboard.ossprey.com/changelog.
Updated 7 days ago