Skip to main content

Using the API

SecretsBuster's API is a REST service using JSON, described by an OpenAPI 3.1 specification. You can also browse it interactively at secretsbuster.com/doc/api.

This page walks through authentication and the core workflow (create a scan, poll it, read the result). For full request/response schemas, field-by-field, use the OpenAPI spec/interactive docs linked above — this page focuses on how the pieces fit together.

Base URL​

https://api.secretsbuster.com/v1

v1 is currently the only available API version.

Authentication​

Every request must include your API key in the X-API-Key header:

curl https://api.secretsbuster.com/v1/accounts/me \
  -H "X-API-Key: YOUR_API_KEY"

Get an API key by subscribing to a plan. A missing or invalid key returns 401 Unauthorized.

Your API key is tied to a usage plan that limits how many reports you can create per period (see API Key and Usage Plan). Only POST /reports consumes quota — every other endpoint is free to call as often as you like.

Create a scan​

curl -X POST https://api.secretsbuster.com/v1/reports \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

This returns 201 Created with a report object in QUEUED state, including a publicId — the identifier you'll use to check on it. Possible errors: 400 if the body isn't a valid {"url": ...} document or the URL is invalid, 403 if you've hit your quota for the period (check /accounts/me to confirm), 401 if authentication failed.

Poll for the result​

curl https://api.secretsbuster.com/v1/reports/{publicId} \
  -H "X-API-Key: YOUR_API_KEY"

Report creation is asynchronous and typically takes 10–30 seconds depending on load and how many resources the target loads. Poll this endpoint until state is CRAWLED or ERROR — while it's QUEUED or CRAWLING, most fields (scan result, findings, timing) aren't populated yet.

Avoid tight polling loops. Since a scan takes at least several seconds, polling more than once every few seconds gains you nothing but load on both ends — a few seconds between checks is enough.

Once state is CRAWLED, check scanResult:

  • SAFE — no secrets found.
  • LEAKY — the secrets array lists every leaky document and what was found in it, including the type and value of each secret and how many times it occurred. See Understanding Scan Results for how to interpret validation and confidence fields shown alongside each finding in the dashboard (the raw API response contains the underlying data; check the OpenAPI schema for exact field names).
  • ERROR — see error (an unexpected failure during crawling) and/or targetDocumentError (the target URL itself couldn't be reached).

Review a report​

curl -X PATCH https://api.secretsbuster.com/v1/reports/{publicId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"review": "Rotated the key, false alarm otherwise confirmed as expected test fixture."}'

This sets a comment (up to 1000 characters, truncated if longer) and records the review time, returned as reviewedAt/review in the report. A report can only be reviewed once it's finished scanning (CRAWLED or ERROR) — reviewing a still-pending report returns 409 Conflict. Reviewing this way records a comment; to set a structured triage category (true positive / false positive / duplicate) as shown in the dashboard, use the dashboard's review form (see Using the Dashboard).

List and filter reports​

curl "https://api.secretsbuster.com/v1/reports?scan_result=LEAKY&reviewed=false&page=1" \
  -H "X-API-Key: YOUR_API_KEY"

Returns every report on your account (across all your API keys, not just the one used for this request), 100 per page. Filter by scan_result (LEAKY, SAFE, ERROR) and/or reviewed (true/false), and page through results with page.

Check your account and quota​

curl https://api.secretsbuster.com/v1/accounts/me \
  -H "X-API-Key: YOUR_API_KEY"

Returns your account email and, for each of your API keys, its usage plan and remaining requests for the current period. Check this before a batch of scans to make sure you won't hit 403s partway through, or after one to confirm remaining quota.

Error responses​

Error responses are a JSON object with a message field describing what went wrong. Standard HTTP status codes apply throughout: 400 for a malformed request, 401 for missing/invalid authentication, 403 for quota exhaustion, 404 for a report that doesn't exist (or doesn't belong to your account), 409 for reviewing a report that isn't finished yet, 500 for an unexpected server-side error.

Next steps​