API Reference

The TesterArmy API allows you to programmatically run AI-powered QA tests against any web application. This RESTful API returns JSON responses and uses standard HTTP status codes.

Base URL

https://tester.army/api/v1

Authentication

All API requests require authentication using a Bearer token. Sign in at /sign-in, then generate an API key in your dashboard.

Include your API key in the Authorization header:

Authorization: Bearer sk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxx

API keys are prefixed with sk_ and should be kept secret. Do not expose them in client-side code or public repositories.

Endpoints

The primary API flow is async test runs via /runs* endpoints.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Error Response Format

{
  "error": "ErrorType",
  "message": "Human-readable error description"
}

Status Codes

Status	Error	Description
`200`	-	Success
`400`	`ValidationError`	Invalid request body. Check the `message` field for details.
`401`	`Unauthorized`	Missing or invalid API key.
`500`	`InternalError`	Server error. Try again later.

Example Error Response

{
  "error": "ValidationError",
  "message": "prompt: Required"
}

Async Test Runs (Recommended)

The async run endpoints return immediately with a run ID. Poll for completion or provide a webhookUrl to receive results.

Submit a QA Test Run

POST /runs

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Description of what to test. Include the target URL in your prompt.
`credentials`	object	No	Optional auth credentials for testing login-protected pages.
`credentials.email`	string	No	Email or username for authentication.
`credentials.password`	string	No	Password for authentication.
`webhookUrl`	string	No	URL to receive a POST callback when the run completes.

Example Request

curl -X POST https://tester.army/api/v1/runs \
  -H "Authorization: Bearer sk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Test the signup button on https://example.com",
    "webhookUrl": "https://example.com/webhooks/tester-army"
  }'

Response (202)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "status": "queued",
  "createdAt": "2026-02-12T00:00:00.000Z"
}

Get a Test Run

GET /runs/{id}

Response (200)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "type": "chat",
  "status": "completed",
  "input": {
    "prompt": "Test the signup button on https://example.com"
  },
  "output": {
    "featureName": "Signup Flow",
    "result": "PASS",
    "description": "No issues found.",
    "issues": [],
    "screenshots": []
  },
  "testPlan": null,
  "error": null,
  "durationMs": 12345,
  "webhookUrl": null,
  "webhookStatus": null,
  "createdAt": "2026-02-12T00:00:00.000Z",
  "startedAt": "2026-02-12T00:00:01.000Z",
  "completedAt": "2026-02-12T00:00:12.000Z"
}

List Test Runs

GET /runs

Query Parameters

Field	Type	Description
`limit`	number	Max results per page (default 20, max 100).
`status`	string	Filter by status (`queued`, `running`, `completed`, `failed`, `cancelled`).
`cursor`	string	Cursor for pagination.

Response (200)

{
  "runs": [
    {
      "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
      "type": "chat",
      "status": "completed",
      "input": {
        "prompt": "Test the signup button on https://example.com"
      },
      "output": null,
      "testPlan": null,
      "error": null,
      "durationMs": null,
      "webhookUrl": null,
      "webhookStatus": null,
      "createdAt": "2026-02-12T00:00:00.000Z",
      "startedAt": null,
      "completedAt": null
    }
  ],
  "nextCursor": "2026-02-12T00:00:00.000Z::c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2"
}

Cancel a Queued Run

POST /runs/{id}/cancel

Only runs in queued status can be cancelled.

Response (200)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "status": "cancelled"
}

Webhook Delivery

If you supply webhookUrl, TesterArmy sends a POST request when the run completes (either completed or failed).

Payload

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "type": "chat",
  "status": "completed",
  "output": {
    "featureName": "Signup Flow",
    "result": "PASS",
    "description": "No issues found.",
    "issues": [],
    "screenshots": []
  },
  "testPlan": null,
  "error": null,
  "durationMs": 12345,
  "createdAt": "2026-02-12T00:00:00.000Z",
  "completedAt": "2026-02-12T00:00:12.000Z"
}

Retries & Timeouts

Retries up to 3 times with exponential backoff (1s, 2s, 4s).
Each request times out after 10 seconds.
webhookStatus updates to delivered or failed after retries.

Project Setup to connect GitHub and Vercel.
Quick Test to validate prompts before API automation.
Getting Started for core platform concepts.

API Reference

On this page