REST API
The HTTP API behind TraceGuard (curated reference, beta).
Beta. This is a curated reference to the most useful endpoints, not an exhaustive contract. Paths are stable; response shapes may still change. For production automation, prefer the GitHub Action or MCP server where they fit.
Base URL & auth
https://app.traceguard.io/api/v1Authenticate with a bearer token (see Authentication & tokens).
Deploy tokens (tgd_) are scoped to one project; PATs (tgp_) and service
tokens (tgs_) act with their principal's permissions.
curl -H "Authorization: Bearer $TOKEN" \
"https://app.traceguard.io/api/v1/organizations/$ORG/projects/$PROJECT/sboms"Org-scoped resources live under /organizations/{org}, and project-scoped ones
under /organizations/{org}/projects/{project}. Every request is bounded by the
token's scopes and organization — you can't read across tenants.
Selected endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /organizations/{org}/projects/{project}/sboms | Upload a BOM (multipart). |
GET | /organizations/{org}/projects/{project}/sboms | List a project's BOMs. |
POST | /organizations/{org}/projects/{project}/scan-now | Trigger a scan. |
GET | /organizations/{org}/vulnerabilities | List vulnerabilities. |
GET | /organizations/{org}/components | List the component inventory. |
GET | /organizations/{org}/dashboard/stats | Org dashboard summary. |
GET | /organizations/{org}/vex · POST …/vex | List / create VEX assertions. |
Upload a BOM
The canonical write path — the same one the GitHub Action uses:
curl -sSf -X POST \
"https://app.traceguard.io/api/v1/organizations/$ORG/projects/$PROJECT/sboms" \
-H "Authorization: Bearer $TRACEGUARD_DEPLOY_TOKEN" \
-F "file=@sbom.cdx.json;type=application/json" \
-F "source_type=ci" \
-F "source_ref=$GIT_SHA" \
-F "bom_type=sbom"Uploads dedupe by content hash, then parse and scan automatically.
Conventions
- Requests and responses are JSON (uploads are
multipart/form-data). - Standard HTTP status codes;
401/403for auth/scope failures,404when a resource is outside your scope. - Be polite with request volume; heavy automation may be rate-limited.