API Reference

Programmatically access Agent Breach through our REST API. Plan limits for targets, scans, and findings are the same as in the web app.

Interactive OpenAPI

Live schemas, request examples, and "Try it" (with your credentials). Swagger and ReDoc are served by the API backend, not this website's /docs hub. They list the public automation API only (targets, scans, findings, auth profiles, schedules, CI, API keys, outbound webhooks, usage)—not the full dashboard surface.

https://api.agentbreach.com/api/docs (Swagger UI; /docs on the API host redirects here when routed to the backend)
https://api.agentbreach.com/api/redoc (ReDoc)

Authentication

Browser / session: use the JWT from login as Authorization: Bearer <jwt>.
Automation (paid plans): create an API key in Settings → Security → API keys. Keys must include the api:access scope for REST endpoints. Send the secret as either:

Authorization: Bearer ab_xxxxxxxx
# or
X-API-Key: ab_xxxxxxxx

Free plan: you cannot create or use REST API keys. CI / PR workflows use separate keys with the ci:scan:write scope and the /ci-scans/... routes only.

Workspace header

Targets, scans, and findings are scoped to a workspace (personal or team), same as the dashboard:

X-Org-Context: personal
# or your team workspace id from the app

Base URL

https://www.agentbreach.com/api/v1

Your app uses NEXT_PUBLIC_API_URL (e.g. the site origin if requests are proxied). Override Swagger/ReDoc host with NEXT_PUBLIC_OPENAPI_ORIGIN when they differ (e.g. https://api.agentbreach.com).

Example requests

Create target

POST https://www.agentbreach.com/api/v1/targets

curl -sS -X POST "https://www.agentbreach.com/api/v1/targets" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com",
    "scope": {
      "include_paths": ["/v1"],
      "exclude_paths": ["/v1/admin"],
      "include_subdomains": false,
      "allow_reverse_ip_discovery": false,
      "ip_ranges": []
    },
    "cross_domain_consent": false
  }'

Create scan

POST https://www.agentbreach.com/api/v1/scans

curl -sS -X POST "https://www.agentbreach.com/api/v1/scans" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "target_id": "550e8400-e29b-41d4-a716-446655440000",
    "profile": "standard",
    "auth_profile_id": null,
    "selected_tools": null,
    "options": {}
  }'

List findings

GET https://www.agentbreach.com/api/v1/findings?limit=20&skip=0 — optional target_id, scan_id, severity, status.

curl -sS "https://www.agentbreach.com/api/v1/findings?limit=10" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "X-Org-Context: personal"

Update finding

PATCH https://www.agentbreach.com/api/v1/findings/{id}

curl -sS -X PATCH "https://www.agentbreach.com/api/v1/findings/FINDING_ID" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{"status": "accepted", "notes": "Risk accepted for this release."}'

Auth profiles (optional)

Create profiles under a target, then pass auth_profile_id when starting a scan.

curl -sS -X POST "https://www.agentbreach.com/api/v1/targets/TARGET_ID/auth-profiles" \
  -H "Authorization: Bearer ab_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Org-Context: personal" \
  -d '{
    "name": "Staging login",
    "type": "cookie",
    "config": {
      "cookie_name": "session",
      "login_url": "https://app.example.com/login"
    }
  }'

Endpoints overview

Targets

GET /targets — List targets
POST /targets — Create target
GET /targets/:id — Get target
PUT /targets/:id — Update target
DELETE /targets/:id — Delete target

Scans

GET /scans/available-tools — Tool catalogue
GET /scans — List scans
POST /scans — Create and queue scan
GET /scans/:id — Get scan
POST /scans/:id/cancel — Cancel
POST /scans/:id/retry — Retry

Findings

GET /findings — List findings (filters: target_id, scan_id, severity, status)
GET /findings/:id — Get finding
PATCH /findings/:id — Update triage fields

CI / PR scans

Requires an API key with ci:scan:write (not the same as api:access).

POST /ci-scans/start — Enqueue PR scan
POST /ci-scans/:id/results — Submit results

Errors

JSON error bodies typically use a detail field (string or nested object for validation):

{ "detail": "Could not validate credentials" }
{ "detail": "Missing required API key scope: api:access" }
{ "detail": [ { "loc": ["body", "url"], "msg": "field required", "type": "value_error.missing" } ] }

Rate limits

Plan-based hourly limits apply to mutating requests; see X-RateLimit-* response headers when enforced. Approximate plan caps:

Free: 100 requests per hour
Startup: 1,000 requests per hour
Pro: 10,000 requests per hour
Enterprise: 100,000 requests per hour

Some routes use stricter per-path limits (e.g. scan creation). Unauthenticated traffic may be keyed by IP.

More help

Browse the documentation hub, OpenAPI links above, or contact support.