API reference
Run tests
Enqueue a single test, a suite, or a whole project with POST /api/v1/runs.
POST /api/v1/runs
One endpoint, three addressing modes. Provide exactly one of testId or projectSlug:
| Mode | Body | Response (201) |
|---|---|---|
| Single test | { "testId": "..." } | { "runId": "..." } |
| One suite | { "projectSlug": "...", "suiteSlug": "..." } | { "suiteRunId": "..." } |
| Whole project | { "projectSlug": "..." } | { "runIds": ["..."] } |
Optional fields in any mode:
baseUrl: overrides the target URL for this run, for example a preview deployment.headers: object of header name to value, sent when loading the target site (basic auth, protection bypass).
Examples
Run one suite against a preview deployment:
curl -X POST https://app.mockingbirdai.com.au/api/v1/runs \
-H "Authorization: Bearer mb_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: build-1234" \
-d '{
"projectSlug": "acme-store",
"suiteSlug": "checkout-flow",
"baseUrl": "https://preview-1234.example.com",
"headers": { "x-vercel-protection-bypass": "..." }
}'Run a single test:
curl -X POST https://app.mockingbirdai.com.au/api/v1/runs \
-H "Authorization: Bearer mb_live_..." \
-H "Content-Type: application/json" \
-d '{ "testId": "9d2f7c1e-1234-4abc-9def-0123456789ab" }'Status codes
| Code | Meaning |
|---|---|
| 201 | Enqueued; body contains runId, suiteRunId, or runIds. |
| 400 | Invalid body, for example both testId and projectSlug, or suiteSlug without projectSlug. |
| 401 | Missing, malformed, invalid, or revoked API key. |
| 403 | Key paused on the Free plan, or the key's creator is no longer a workspace member. |
| 404 | Project or suite not found in the key's workspace. |
| 422 | The run could not be enqueued, for example plan limits. |
| 429 | Rate limit exceeded (60 requests per minute per key). |