API Reference

Programmatically interact with Plaintest.

API Reference

The Plaintest API allows you to programmatically trigger tests and retrieve results.

Authentication

All API requests require an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.plaintest.dev/api/v1/...

Creating an API Key

  1. Go to Settings > API Keys
  2. Click Create API Key
  3. Copy the key (shown only once)

Base URL

https://console.plaintest.dev/api/v1

Endpoints

Trigger Test Run

POST /test-runs

Start a new test run for a project.

Request Body:

{
  "projectId": "string",
  "branch": "string (optional)",
  "commit": "string (optional)",
  "testMode": "full | promoted_only (optional)"
}

Response:

{
  "id": "test-run-id",
  "status": "pending",
  "projectId": "project-id",
  "createdAt": "2024-01-15T10:00:00Z"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "abc123"}' \
  https://console.plaintest.dev/api/v1/test-runs

Get Test Run

GET /test-runs/:id

Get the status and results of a test run.

Response:

{
  "id": "test-run-id",
  "status": "completed",
  "projectId": "project-id",
  "results": {
    "total": 10,
    "passed": 9,
    "failed": 1
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:05:00Z"
}

List Test Runs

GET /projects/:projectId/test-runs

List recent test runs for a project.

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | limit | number | Max results (default: 20) | | offset | number | Pagination offset | | status | string | Filter by status |

Response:

{
  "testRuns": [...],
  "total": 50,
  "limit": 20,
  "offset": 0
}

Get Test Results

GET /test-runs/:id/results

Get detailed results for each test in a run.

Response:

{
  "results": [
    {
      "id": "result-id",
      "testName": "Login flow",
      "status": "passed",
      "duration": 5234,
      "screenshots": ["url1", "url2"]
    }
  ]
}

List Projects

GET /projects

List all projects in your organization.

Response:

{
  "projects": [
    {
      "id": "project-id",
      "name": "My App",
      "baseUrl": "https://myapp.com",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Webhooks

Configure webhooks to receive notifications.

Events

| Event | Description | |-------|-------------| | test_run.started | Test run has started | | test_run.completed | Test run finished (pass or fail) | | test_run.failed | Test run had failures |

Payload

{
  "event": "test_run.completed",
  "timestamp": "2024-01-15T10:05:00Z",
  "data": {
    "testRun": {
      "id": "test-run-id",
      "status": "completed",
      "projectId": "project-id",
      "results": {
        "total": 10,
        "passed": 9,
        "failed": 1
      }
    }
  }
}

Verifying Webhooks

Webhooks include a signature header for verification:

X-Plaintest-Signature: sha256=...

Verify using HMAC-SHA256 with your webhook secret.

Rate Limits

| Endpoint | Limit | |----------|-------| | All endpoints | 100 requests/minute | | Test run creation | 10 requests/minute |

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Error Responses

{
  "error": {
    "code": "invalid_request",
    "message": "Project not found"
  }
}

| Code | Description | |------|-------------| | invalid_request | Malformed request | | unauthorized | Invalid or missing API key | | forbidden | Insufficient permissions | | not_found | Resource not found | | rate_limited | Too many requests |

SDKs

Coming soon:

  • JavaScript/TypeScript SDK
  • Python SDK

For now, use direct HTTP requests or curl.

Next Steps