API reference

Automate BugSafer from CI, scripts, or your own dashboards. Trigger scans, pull findings and reports, and manage schedules — all over a clean REST API.

Base URL

https://<your-app>/api/v1

Authentication

Create a key under Settings → API keys and send it as a Bearer token. The key is shown once — store it securely.

curl https://<your-app>/api/v1/projects \
  -H "Authorization: Bearer bf_your_api_key"

Scopes

Each key has a scope. Read-only keys may call GET endpoints only; a mutating request returns 403. Full access keys can also start scans and manage schedules.

Responses

Every response is JSON wrapped in a standard envelope. Errors use the same shape with success: false and an error object.

// success
{
  "success": true,
  "data": { "scan": { "id": "scn_9f3a", "status": "QUEUED" } },
  "requestId": "req_..."
}

// error
{
  "success": false,
  "error": { "code": "FORBIDDEN",
             "message": "This API key is read-only." },
  "requestId": "req_..."
}

Rate limits

Requests are rate-limited per client. Every response carries standard headers so you can back off gracefully; exceeding the limit returns 429.

RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 42

Prefer generated clients? Grab the machine-readable spec:

/api/v1/openapi.json· OpenAPI 3.1

Scans

POST/projects/{id}/scansStart a scan on a repository.full

GET/scans?repositoryId={id}&page=1&pageSize=20List your scans (paginated, newest first).read

GET/scans/{id}Get a single scan with live status and counters.read

POST/scans/{id}/retryRe-run a completed or failed scan.full

Findings

GET/findings?repositoryId={id}&severity=CRITICAL&status=OPENList findings; filter by scan, repo, severity or status.read

GET/findings/{id}Get one finding with evidence and fix guidance.read

Projects

GET/projectsList connected repositories.read

GET/projects/{id}Get a single repository.read

GET/projects/{id}/branchesList a repository’s branches.read

Reports

GET/reports?repositoryId={id}List generated reports.read

GET/reports/{id}Get a report’s full data.read

GET/reports/{id}/download?format=json|csv|html|pdf|sbom|complianceDownload a report (compliance = SOC2/ISO/PCI control gaps).read

Schedules

GET/schedulesList your automatic scan schedules.read

POST/schedulesCreate a schedule (name, repositoryId, branch, cadence).full

PATCH/schedules/{id}Update a schedule (cadence, enabled, …).full

DELETE/schedules/{id}Delete a schedule.full

Example: scan on every merge

Trigger a scan from CI, then poll until it finishes and read the score.

# 1) start a scan
SCAN=$(curl -s -X POST https://<your-app>/api/v1/projects/$REPO_ID/scans \
  -H "Authorization: Bearer $BUGFINDER_KEY" | jq -r '.data.scan.id')

# 2) poll status
curl -s https://<your-app>/api/v1/scans/$SCAN \
  -H "Authorization: Bearer $BUGFINDER_KEY" | jq '.data.scan.status'

# 3) read the findings once COMPLETED
curl -s "https://<your-app>/api/v1/findings?scanId=$SCAN&severity=CRITICAL" \
  -H "Authorization: Bearer $BUGFINDER_KEY" | jq '.data.total'

Ready to automate?

Create a key and make your first request in a minute.

Get an API key