Public API

The Barrion API lets a pipeline or a script do what you would otherwise do in the dashboard: check your credits, start a passive scan or an AI pentest, read the results, and see what a run cost.

It works exactly like the dashboard. Runs spend the same credits at the same prices, need the same verified targets, and follow the same rules for who in an organization can do what. An API run shows up in the dashboard like any other.

Base URL

https://api.barrion.io/v1

Every request is JSON over HTTPS, authenticated with an API key in the Authorization header.

The examples use this address. If you were given a different one to test against, replace https://api.barrion.io/v1 in them with that.

The shell examples are for bash, which includes Git Bash on Windows and the shells in GitHub Actions and GitLab CI. In Windows PowerShell, curl is a different command with different options: use curl.exe, write each command on one line instead of continuing lines with \, or run the examples in Git Bash.

Quick start

1. Create a key. In the dashboard, open Settings, then API keys, and create a key. Give it the permissions it needs and a credit budget. The full key is shown once, so copy it into your CI secret store straight away.

2. Check it works.

curl https://api.barrion.io/v1/credits/balance \
  -H "Authorization: Bearer $BARRION_API_KEY"

{ "available": 1000, "held": 0, "plan": 1000, "purchased": 0, "nextExpiry": null, ... }

3. Start a passive scan. Scans are free and take a few minutes.

curl -X POST https://api.barrion.io/v1/scans \
  -H "Authorization: Bearer $BARRION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-scan" \
  -d '{"url": "https://example.com"}'

{ "id": "5b1c...", "domain": "example.com", "status": "STARTED" }

Then poll GET /v1/scans/{id} until status is COMPLETED.

4. Start a pentest once you have verified a target and turned on API runs for it. See Pentests.

What you can do

Before you build on it

• Starts need an Idempotency-Key. Both start endpoints require one, so a retried request can never start and charge a second run. See Errors and limits.
• Pentests take hours. Start one, keep its id, and check back later. The CI recipes show a pipeline that does not sit and wait.
• A finished pentest is charged at least 100 credits, even if it runs for two minutes. See Credits.
• Retests, webhooks and code scanning are not in the API yet. Use the dashboard for those.

Versioning

The version is in the path: /v1. Within /v1, a change never breaks an integration that follows the rules below. A breaking change would come as a new version beside it.

What stays the same within /v1:

• Fields are not removed or renamed, and their types do not change.
• A request field that is optional does not become required, and a value that is accepted today is not refused later.
• An endpoint's meaning, its status codes and its error codes do not change.

What can be added, so your client should allow for it:

• New endpoints, and new optional request fields.
• New fields in a response. Ignore fields you do not recognise, and do not parse responses so strictly that an extra field fails.

New pentest statuses. The pentest tool is under active development, so a pentest's status can gain new values within /v1. Existing statuses keep their names and meaning. This applies to a pentest's status only: other lists, such as a scan's status and a pentest's credits.state, do not change within /v1.

Values you do not recognise. Handle an unknown value in an enum field, such as a pentest's status, safely:

• Never treat it as success. A pipeline that gates on a pentest should pass only on COMPLETED with a released report.
• Keep polling with a limit on how long you wait, then stop and report the value as unsupported, rather than polling forever. An unknown status could be a failure or need someone to act.
• A pentest's credits.state describes billing only. Use status to decide whether a run has finished.

When a new version ships. Security fixes are applied to every supported version where that is possible, so you do not have to move just to stay safe. When moving is required, the deadline depends on the change and is announced with it. A security-critical change can require you to move within one month or less. There is no fixed support period for every earlier version.