API Reference¶

The /api/v1 contract is frozen for the current major version. See the Versioning & Deprecation Policy for stability guarantees, deprecation rules, and removal timelines.

The machine-readable OpenAPI schema is served at /api/openapi.json (committed copy for offline browsing). Browse it in the docs at ReDoc.

Authentication¶

All /api/v1/* endpoints require an API key passed via the Authorization: Bearer header:

curl -H "Authorization: Bearer argus_xxxxxxxxxxxx" http://localhost:8000/api/v1/...

gRPC endpoints require the authorization: bearer metadata header.

REST API Endpoints¶

Projects¶

Method	Path	Description
`GET`	`/api/v1/projects`	List projects (paginated, filterable)
`POST`	`/api/v1/projects`	Create project
`GET`	`/api/v1/projects/{id}`	Get project details
`PATCH`	`/api/v1/projects/{id}`	Update project
`DELETE`	`/api/v1/projects/{id}`	Delete project and cascade

Project responses include a slug field — a stable, readable identifier generated from the project name (e.g. Argus SBOM Guard → argus-sbom-guard).

SBOMs¶

Method	Path	Description
`POST`	`/api/v1/sboms/upload`	Upload SBOM file (multipart) — by project UUID or project slug
`GET`	`/api/v1/sboms/{id}`	Get SBOM with deps + vulns
`GET`	`/api/v1/sboms/{id}/download`	Download raw SBOM JSON
`GET`	`/api/v1/sboms/{id}/diff/{other_id}`	Diff two SBOM versions
`DELETE`	`/api/v1/sboms/{id}`	Delete SBOM

POST /api/v1/sboms/upload targets a project by exactly one of project_id (UUID) or project_slug:

Services¶

Method	Path	Description
`GET`	`/api/v1/services`	List services for a project (`project_id` required)
`DELETE`	`/api/v1/services/{id}`	Delete service

Vulnerabilities¶

Method	Path	Description
`GET`	`/api/v1/vulnerabilities/active`	List actionable (open, non-accepted) vulns
`GET`	`/api/v1/vulnerabilities/summary`	Vulnerability counts by severity
`GET`	`/api/v1/vulnerabilities/acceptances`	List risk acceptances (optionally per project)
`POST`	`/api/v1/vulnerabilities/acceptances`	Accept a vulnerability (project or service scope)
`DELETE`	`/api/v1/vulnerabilities/acceptances/{id}`	Revert a risk acceptance

Alert Rules¶

Method	Path	Description
`GET`	`/api/v1/alert-rules`	List alert rules
`POST`	`/api/v1/alert-rules`	Create alert rule
`PATCH`	`/api/v1/alert-rules/{id}`	Update alert rule
`DELETE`	`/api/v1/alert-rules/{id}`	Delete alert rule

Pagination¶

Paginated endpoints accept page and per_page query parameters:

curl "http://localhost:8000/api/v1/projects?page=1&per_page=20" \
  -H "Authorization: Bearer argus_xxx"

Response includes:

{
  "items": [...],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "total_pages": 3,
  "has_more": true
}

Filtering & Sorting¶

Most list endpoints support:

sort: Column to sort by (varies per resource)
order: asc or desc
project_id: Filter by project
service_id: Filter by service
severity: Filter vulnerabilities by severity

Example:

curl "http://localhost:8000/api/v1/sboms?sort=uploaded_at&order=desc&project_id={id}" \
  -H "Authorization: Bearer argus_xxx"

gRPC¶

The SBOM upload gRPC service is defined in protos/sbom.proto and served on port 50051.

service SBOMService {
  rpc UploadSBOM (UploadSBOMRequest) returns (UploadSBOMResponse);
}

Use grpcurl for testing:

grpcurl -plaintext \
  -H 'authorization: bearer argus_xxx' \
  localhost:50051 list