API Overview

AegisRunner has a REST API for triggering scans, runs, fetching results, and managing your account programmatically. This page covers authentication, the major endpoints, rate limits, and idiomatic patterns.

Base URL

https://aegisrunner.com/api/v1

All endpoints are HTTPS. We don’t accept HTTP requests — they redirect with a 308.

Authentication

Every authenticated request needs an Authorization header:

Authorization: Bearer aegis_<token>

For request payloads where context (which project, which user) needs to be inferred, use a CI trigger token from the relevant project. The token’s project scope determines which resources you can read or modify.

Major endpoints

Trigger a scan or run

POST /api/v1/ci/triggerAuthorization: Bearer aegis_<ci-token>

See CI/CD Integration for the full payload. A scan trigger returns a crawl_id.

To scan pages behind a login, add credentials and/or authRole to a {“crawl”: true} payload:

{  “crawl”: true,  “baseUrl”: “https://staging.example.com”,  “credentials”: { “username”: “qa@example.com”, “password”: ”…” },  “authRole”: “Admin”  // optional: scan as a saved role}

username can be any identity the login form uses — email, username, phone — the scanner maps it onto the form automatically. Send credentials over HTTPS only (the API rejects HTTP); they’re stored on the project’s login so authenticated runs and re-scans reuse them. This is what aegis scan —username/—password-stdin/—role sends.

Stream scan progress (SSE)

GET /api/v1/ci/crawls/<crawlId>/eventsAuthorization: Bearer aegis_<ci-token>Accept: text/event-stream

A Server-Sent Events stream of live scan progress — both the crawl and the AI test-generation phases — scoped to the token’s project. Each frame is event: <type> + data: <json>. Event types: connected, crawl_progress, ai_generation_progress, and a terminal done ({“result”:“completed”|“failed”}) after which the stream closes. Comment lines (: ping) are keep-alives. If you connect after the scan already finished, you get an immediate done. This is what aegis scan —watch consumes; use it directly to render progress in your own tooling.

Get run status

GET /api/v1/ci/runs/<runId>Authorization: Bearer aegis_<ci-token>

Returns status, pass/fail counts, duration, link to the run page.

List projects (in your auth scope)

GET /api/v1/projectsAuthorization: Bearer aegis_<token>

Get project

GET /api/v1/projects/<projectId>

List scans for a project

GET /api/v1/projects/<projectId>/crawls   ?page=1&pageSize=20

Get scan result

GET /api/v1/crawls/<crawlId>

List test suites

GET /api/v1/projects/<projectId>/suites   ?page=1&pageSize=50

Get test suite

GET /api/v1/suites/<suiteId>

Run a suite

POST /api/v1/suites/<suiteId>/run{  “browserProfile”: “chromium”,  “environmentId”: ”…”}

List test runs

GET /api/v1/projects/<projectId>/runs   ?status=failed&page=1&pageSize=20

Export a suite as Playwright

GET /api/v1/suites/<suiteId>/export/playwright

Returns the spec as JSON. Add ?download=true for a file download.

Pagination

List endpoints support page and pageSize query parameters:

GET /api/v1/projects/<id>/runs?page=2&pageSize=50

Default pageSize is 20, max 200.

Responses include totalCount:

{  “items”: […],  “totalCount”: 1247,  “page”: 2,  “pageSize”: 50}

Rate limits

Rate limits are per-token. Hitting the limit returns 429 with a Retry-After header.

Recommended pattern

Implement exponential backoff: 1s, 2s, 4s, 8s. Honor Retry-After if present.

Errors

Error responses follow this shape:

{  “error”: “Invalid token”,  “code”: “auth.invalid_token”,  “details”: { … }}

Webhooks (incoming)

If you’ve configured outbound webhooks under Notifications, AegisRunner POSTs to your URL on each event with HMAC-SHA256 signing. Verify the signature before acting on the payload.

Versioning

The current API is v1. We commit to non-breaking changes within v1 — adding fields, adding endpoints, never removing or changing existing field meanings. Major changes go in v2 with overlap.

Common patterns

Trigger run, poll for completion

# TriggerRESPONSE=$(curl -fsSL -X POST https://aegisrunner.com/api/v1/ci/trigger \  -H “Authorization: Bearer aegis_$TOKEN” \  -d ’{“crawl”: true}‘)RUN_ID=$(echo $RESPONSE | jq -r .runId)# Pollwhile true; do  STATUS=$(curl -fsSL https://aegisrunner.com/api/v1/ci/runs/$RUN_ID \    -H “Authorization: Bearer aegis_$TOKEN” | jq -r .status)  case “$STATUS” in    passed)  echo “PASS”; exit 0 ;;    failed)  echo “FAIL”; exit 1 ;;    queued|running) sleep 10 ;;    *) echo “Unknown: $STATUS”; exit 2 ;;  esacdone

Or just block

Pass “wait”: true in the trigger payload — the request blocks until completion, returns the final status. Up to 10 minutes.

SDKs

We don’t ship official SDKs yet. The API is small and well-documented enough that the curl/fetch you’d write is shorter than configuring an SDK. Common libraries (Octokit-style helpers) are on the roadmap.

Common questions

Related

• CI/CD Integration — the most common API entry point.
• Account Settings — managing personal tokens.
• Notifications & Alerts — outbound webhooks.