Bidvix API

Run site diagnoses programmatically and pull reports into your own tools. Prepaid credits — each successful scan costs 1 credit, failed scans are never charged.

Authentication

All endpoints require an API key sent as a Bearer token. Create a key in your dashboard → API & Credits. The full key is shown only once at creation — store it somewhere safe; we keep only a hash and can never recover it for you.

Authorization: Bearer bv_live_0123456789abcdef0123456789abcdef

Every authenticated response includes an X-Credits-Remaining header.

Endpoints

POST/v1/scans202 Accepted

Start a diagnosis for a domain. Returns immediately with a job id — diagnoses take 30–90 seconds. 1 credit is charged only when the scan completes successfully.

curl -X POST https://your-domain/v1/scans \
  -H "Authorization: Bearer bv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

{
  "ok": true,
  "jobId": "f2a1…",
  "domain": "example.com",
  "status": "queued",
  "poll": "/v1/scans/f2a1…"
}

GET/v1/scans/:jobIdPolling

Check job status. While queued/running, you get progress fields; when done, the full report is included. Job records are kept for about 60 minutes after completion — pull the report and store it on your side.

{
  "ok": true,
  "jobId": "f2a1…",
  "domain": "example.com",
  "status": "done",
  "overall": 62,
  "report": { … }
}

GET/v1/scans/:domain/latestReport

Fetch the latest completed report for a domain on your account, without running a new scan. No credits are consumed.

GET/v1/credits/balanceAccount

Current credit balance, cost per scan and the 5 most recent transactions.

Errors & status codes

Status	error	Meaning
401	`invalid_api_key`	Missing, malformed or revoked key.
400	`invalid_domain`	Domain format failed validation.
400	`domain_not_reachable`	Domain does not resolve or is not publicly reachable.
402	`insufficient_credits`	Balance below 1 credit. Top up to continue.
404	`not_found`	Unknown job (or poll window expired) / no completed scan for the domain.
429	`busy`	Too many diagnoses running — retry shortly.

5xx responses always return JSON with ok: false; failed scans are never charged.

Credits & limits

1 credit = 1 successful API diagnosis (web scans in your dashboard do not consume credits).
API and web scans share a global concurrency limit; keep polling intervals at 3–5 seconds.
Domains must be publicly reachable — private/internal addresses are rejected.

Credits pricing and top-up options are in your Billing page. 1 credit = 1 successful API scan.

Quickstart

# 1. start a scan
curl -X POST https://your-domain/v1/scans \
  -H "Authorization: Bearer bv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# 2. poll until status === "done"
curl https://your-domain/v1/scans/<jobId> -H "Authorization: Bearer bv_live_…"

# 3. fetch the stored report any time later
curl https://your-domain/v1/scans/example.com/latest -H "Authorization: Bearer bv_live_…"