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.

Base URL

https://api.aegisrunner.com/v1

Authentication

All API requests require authentication using a Bearer token.

Getting Your API Key

1. Go to Settings → Security
2. Scroll to API Keys
3. Click Generate API Key
4. Copy and securely store the key

Using Your API Key

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

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