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/trigger
Authorization: Bearer aegis_<ci-token>

See CI/CD Integration for the full payload.

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/projects
Authorization: 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

# Trigger
RESPONSE=$(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)

# Poll
while 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 ;;
  esac
done

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.