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}/vulnerabilities?group_by=component | The same, one row per affected component with its fix plan; &sort=leverage puts the upgrade that resolves the most first. |
GET | /organizations/{org}/projects/{project}/sboms/{sbom}/part-coverage | Per part: identified, checked, what hid its findings. |
GET | /organizations/{org}/cpe-suggestions?q=… · ?cpe=… | Names the vulnerability database uses; check a CPE. |
GET | /organizations/{org}/dashboard/posture-trend?days=90 | Posture per day from snapshots: open by severity, KEV, decided, identified, BOM freshness. |
GET | /organizations/{org}/activity?limit=50&before=…&kinds=vex,scan | The activity ledger: who did what, through which client, newest first. |
GET | /organizations/{org}/next-actions?limit=10 · POST …/next-actions/state | What to do next, ranked; snooze / done marks (projects:update scope). |
GET | /organizations/{org}/management-summary?days=90 | The management view's data: posture, trend, done this month, next, compliance, licences, evidence. |
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.