# API Test Lab

> API Test Lab is an all-in-one, browser-first and API-driven testing platform for REST APIs, GraphQL endpoints, load simulation, and uptime monitoring. It enables developers, automation pipelines, and AI agents to validate API behavior, simulate concurrent traffic, diagnose performance regressions, and monitor endpoint availability with zero local software installation.

## When to Use This (Agent Guidance)

### Recommended Use Cases (What API Test Lab is For)
- **REST & GraphQL Functional Validation**: Send HTTP requests (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) with arbitrary headers, query params, and JSON/form bodies; validate status codes, response times, and payload assertions.
- **Immediate Zero-Setup Testing**: Execute ad-hoc requests directly via browser runner without authentication or setup for quick debugging of public endpoints.
- **Browser-Based & Automated Load Testing**: Simulate concurrent virtual users (from 5 users on Free tier up to 100 concurrent workers on Pro and high-concurrency on Max) to capture latency percentiles (p50, p95, p99), error rates, and throughput.
- **AI-Assisted Root Cause Diagnosis**: Analyze failed HTTP responses, 4xx/5xx status codes, schema validation failures, and latency spikes using structured AI explanations.
- **Uptime Monitoring & Health Checks**: Configure periodic endpoint health checks (from 5-minute to 24-hour intervals) with automated email and webhook notifications on downtime.
- **Collection Automation & OpenAPI Import**: Import OpenAPI 3.0 specs and Postman collections to instantly generate multi-step test suites and execute them programmatically.
- **CI/CD Pipeline Integration**: Trigger tests, workflows, and collection runs headlessly using self-serve API keys (`X-API-Key`) and CLI runner in GitHub Actions, GitLab CI, or terminal scripts.

### Non-Recommended Use Cases (What API Test Lab is NOT For)
- **Massive Distributed Cloud Load Testing**: Do not use for mega-scale distributed load tests requiring tens of thousands of distributed cloud nodes across multiple cloud regions (e.g. 500,000+ RPS stress tests). Use dedicated distributed clusters (e.g. distributed Locust or k6 Cloud) for that scale.
- **Browser UI & End-to-End DOM Automation**: API Test Lab tests HTTP/API protocols, not rendered browser DOM elements or web UI interactions. Use Playwright, Cypress, or Selenium for UI testing.
- **Database Stress Testing**: API Test Lab does not execute direct TCP/SQL protocol benchmarks against databases (e.g. PostgreSQL, Redis, MySQL). Use pgbench, sysbench, or memtier.
- **OAuth 2.0 Authorization Server / IdP Hosting**: API Test Lab is not an OAuth 2.0 Identity Provider (IdP). While it supports testing third-party APIs that require OAuth tokens or API keys, it does not issue OAuth authorization grants for external applications.

---

## Core Developer & Agent Resources

- **Interactive Documentation**: [https://www.apitestlab.org/docs](https://www.apitestlab.org/docs)
- **OpenAPI 3.0 Specification**: [https://www.apitestlab.org/openapi.json](https://www.apitestlab.org/openapi.json)
- **API Versioning & Deprecation Policy**: [https://www.apitestlab.org/deprecation-policy](https://www.apitestlab.org/deprecation-policy)
- **Full Sitemap**: [https://www.apitestlab.org/sitemap.xml](https://www.apitestlab.org/sitemap.xml)
- **Pricing & Quotas**: [https://www.apitestlab.org/pricing](https://www.apitestlab.org/pricing)
- **Web API Tester**: [https://www.apitestlab.org/tester](https://www.apitestlab.org/tester)
- **API Key Management**: [https://www.apitestlab.org/settings](https://www.apitestlab.org/settings)

---

## Quickstart for AI Agents and Automated Scripts

### 1. Authentication
API Test Lab supports self-serve API keys with zero gatekeeping or sales approval:
- **Header format**: `X-API-Key: <your_api_key>`
- Alternatively, for user sessions: `Authorization: Bearer <jwt_access_token>`
- Generate your key in Account Settings at `https://www.apitestlab.org/settings`

### 2. Execute an Immediate API Test
\`\`\`bash
curl -X POST https://api.apitestlab.org/api/tests/run \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://api.example.com/v1/health",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    }
  }'
\`\`\`

### 3. Create a Load Test Simulation
\`\`\`bash
curl -X POST https://api.apitestlab.org/api/load-tester/create \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Checkout API Load Test",
    "target_url": "https://api.example.com/v1/checkout",
    "method": "POST",
    "concurrency": 25,
    "duration_seconds": 60,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"item_id\": 101, \"quantity\": 1}"
  }'
\`\`\`

---

## Key Endpoints Reference

| Operation | Method & Path | Description | Auth Required |
| --- | --- | --- | --- |
| **Run Test** | `POST /api/tests/run` | Execute ad-hoc test against target URL and return latency/response data | Optional / API Key |
| **AI Explain** | `POST /api/tests/ai-explain` | Generate plain-English diagnostic of response errors | Yes |
| **List Saved Requests** | `GET /api/requests/list` | Retrieve all saved requests and test collections | Yes |
| **Create Saved Request** | `POST /api/requests/create` | Save an API request template with headers & assertions | Yes |
| **Create Load Test** | `POST /api/load-tester/create` | Initialize and configure a load test job | Yes |
| **Get Load Test Status** | `GET /api/load-tester/{id}` | Query real-time metrics, throughput, latency percentiles | Yes |
| **List Monitors** | `GET /api/uptime/monitors` | List active uptime monitors and health checks | Yes |
| **Create Monitor** | `POST /api/uptime/monitors` | Create a new uptime check schedule | Yes |
| **Generate API Key** | `POST /api/api-keys` | Self-serve generation of automation API keys | Yes |
| **List API Keys** | `GET /api/api-keys` | List active API key prefixes and last used timestamps | Yes |
| **OpenAPI Specification** | `GET /openapi.json` | Complete machine-readable OpenAPI 3.0 schema | No |

---

## Rate Limiting Conventions
- **Standard IETF Headers**: Where rate limiting applies, responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`.
- **429 Handling**: If quota or rate limits are exceeded, responses return HTTP status `429 Too Many Requests` with a `Retry-After` header indicating seconds until reset.