API Overview

The AegisRunner API allows you to programmatically interact with your testing infrastructure. Trigger crawls, run tests, retrieve results, and integrate with your existing tools and workflows.

Availability: API access is available on Pro ($29/mo) and Business ($59/mo) plans.

Base URL

https://api.aegisrunner.com/v1

Authentication

All API requests require authentication using a Bearer token.

Getting Your API Key

Go to Settings → Security
Scroll to API Keys
Click Generate API Key
Copy and securely store the key

Using Your API Key

curl https://api.aegisrunner.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Security: Keep your API keys secret. Never expose them in client-side code or commit them to version control.

Response Format

All responses are JSON with consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created successfully
`400`	Bad request (invalid parameters)
`401`	Unauthorized (invalid/missing API key)
`403`	Forbidden (insufficient permissions)
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

Plan	Requests/Minute
Pro	60
Business	300

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642521600

API Endpoints

Projects

Method	Endpoint	Description
`GET`	/projects	List all projects
`GET`	/projects/:id	Get project details
`POST`	/projects	Create a new project
`PUT`	/projects/:id	Update a project
`DELETE`	/projects/:id	Delete a project

Crawls

Method	Endpoint	Description
`GET`	/crawls	List crawls
`GET`	/crawls/:id	Get crawl details and results
`POST`	/crawls	Start a new crawl

Test Suites

Method	Endpoint	Description
`GET`	/suites	List test suites
`GET`	/suites/:id	Get suite details
`GET`	/suites/:id/export	Export as Playwright code
`DELETE`	/suites/:id	Delete a suite

Test Runs

Method	Endpoint	Description
`GET`	/runs	List test runs
`GET`	/runs/:id	Get run details and results
`POST`	/runs	Trigger a new test run

Schedules

Method	Endpoint	Description
`GET`	/schedules	List schedules
`POST`	/schedules	Create a schedule
`PUT`	/schedules/:id	Update a schedule
`DELETE`	/schedules/:id	Delete a schedule

Example Requests

Trigger a Test Run

curl -X POST https://api.aegisrunner.com/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suite_id": "suite_abc123",
    "browser": "chromium"
  }'

Get Run Status

curl https://api.aegisrunner.com/v1/runs/run_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": "run_xyz789",
    "suite_id": "suite_abc123",
    "status": "passed",
    "browser": "chromium",
    "passed": 15,
    "failed": 0,
    "skipped": 2,
    "duration": 45000,
    "started_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:30:45Z"
  }
}

Start a Crawl

curl -X POST https://api.aegisrunner.com/v1/crawls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "mode": "full",
    "max_pages": 100,
    "depth": 3
  }'

Pagination

List endpoints support pagination:

GET /runs?page=2&limit=20

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Webhooks

Configure webhooks to receive notifications when events occur:

run.completed - Test run finished
run.failed - Test run had failures
crawl.completed - Crawl finished

Webhook payloads include event type and relevant data.

SDKs and Libraries

Official SDKs coming soon. In the meantime, use any HTTP client:

JavaScript - fetch, axios
Python - requests, httpx
Go - net/http
Ruby - httparty, faraday

Related Documentation

CI/CD Integration - Use API in pipelines
Slack Integration - Webhook notifications
Account Settings - Manage API keys

API Reference

Articles

API Overview

Need help?