Testnova API Reference

⚡ Overview

The Testnova API lets you automate your entire QA workflow — from requirement to report — without touching the dashboard.

📁

Projects

Base URL https://my.testnova.app

🔑 Authentication

All API requests require a Testnova API key. Generate one from your dashboard under Settings → API Keys.

Bearer token

Pass your API key in the Authorization header on every request:

curl

curl https://my.testnova.app/api/testnova/projects \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Key format

Live keys start with tn_live_. Test keys start with tn_test_. Keys are scoped to your workspace — all requests operate on data within your organisation.

⚠️ Errors & Rate Limits

The API uses standard HTTP status codes and returns JSON error bodies.

Error response shape

json

{
  "error":  "Project not found",
  "detail": "No project with slug 'my-app' in your workspace"
}

200Success — response body contains the resource(s)

400Bad request — missing or invalid parameters

401Unauthorised — API key missing, invalid, or revoked

429Rate limited — 300 requests / minute per API key

404Not found — resource does not exist in your workspace

📁 Projects

Projects are the top-level container for test cases, scripts, runs, and integrations. Every other resource belongs to a project.

GET /api/testnova/projects List all projects in your workspace

curl

curl https://my.testnova.app/api/testnova/projects \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

response

{
  "projects": [{
    "id":      "proj_01...",
    "slug":    "my-web-app",
    "name":    "My Web App",
    "status":  "active",
    "platform": "web",
    "appUrl":  "https://my-app.com"
  }]
}

GET /api/testnova/projects/{slug} Get a single project by slug

Path parameters

Parameter	Type	Description
slugrequired	string	The project slug (from the projects list)

curl

curl https://my.testnova.app/api/testnova/projects/my-web-app \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

🧪 Test Cases

Test cases are structured descriptions of what to test — the what, not the how. Testnova generates them from plain-English requirements, then converts them into executable scripts.

GET /api/testnova/test-cases List test cases across all projects

Query parameters

Parameter	Type	Description
projectSlugoptional	string	Filter by project slug
limitoptional	number	Max results to return (default 50, max 200)

curl

curl "https://my.testnova.app/api/testnova/test-cases?projectSlug=my-web-app" \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

POST /api/testnova/generate-test-cases Generate AI test cases from a requirement

Request body

Field	Type	Description
projectSlugrequired	string	The project to generate cases for
requirementrequired	string	Plain-English feature description (max 4000 chars)
countoptional	number	Number of cases to generate (default 10, max 50)

curl

curl -X POST https://my.testnova.app/api/testnova/generate-test-cases \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "my-web-app",
    "requirement": "User can log in with email and password",
    "count": 10
  }'

response

{
  "cases": [{
    "id":       "tc_01...",
    "title":   "Valid login with correct credentials",
    "priority": "critical",
    "steps":   [...]
  }],
  "generated": 10
}

📜 Test Scripts

Scripts are runnable Playwright (web), Appium (mobile), or raw HTTP (API) test files generated from test cases. Run them individually or as a full suite.

GET /api/testnova/test-scripts List test scripts across all projects

Query parameters

Parameter	Type	Description
projectSlugoptional	string	Filter by project slug
platformoptional	string	`web` \| `mobile` \| `api`
statusoptional	string	`passing` \| `failing` \| `pending`

curl

curl "https://my.testnova.app/api/testnova/test-scripts?projectSlug=my-web-app&platform=web" \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

POST /api/testnova/generate-test-scripts Generate scripts from existing test cases

Request body

Field	Type	Description
projectSlugrequired	string	Target project
caseIdsoptional	string[]	Specific case IDs to generate scripts for (default: all pending)
platformoptional	string	`web` \| `mobile` \| `api` (default: project default)

curl

curl -X POST https://my.testnova.app/api/testnova/generate-test-scripts \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "projectSlug": "my-web-app", "platform": "web" }'

POST /api/testnova/test-scripts/{id}/run Execute a single test script

Path parameters

Parameter	Type	Description
idrequired	string	Script ID from the list endpoint

curl

curl -X POST https://my.testnova.app/api/testnova/test-scripts/scr_01.../run \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

POST /api/testnova/test-scripts/{id}/regenerate Regenerate a script using the latest DOM snapshot

curl

curl -X POST https://my.testnova.app/api/testnova/test-scripts/scr_01.../regenerate \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

▶️ Test Runs

A run is a full execution of all (or selected) scripts in a project. Runs are executed in the cloud against your live app.

GET /api/testnova/runs List recent runs across all projects

Query parameters

Parameter	Type	Description
projectSlugoptional	string	Filter by project
statusoptional	string	`queued` \| `running` \| `passed` \| `failed`
limitoptional	number	Max results (default 20, max 100)

curl

curl "https://my.testnova.app/api/testnova/runs?projectSlug=my-web-app&status=failed" \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

response

{
  "runs": [{
    "id":        "run_01...",
    "status":    "passed",
    "passed":    24,
    "failed":    2,
    "durationMs": 47200,
    "createdAt":  "2026-06-06T09:12:00Z"
  }]
}

GET /api/testnova/projects/{slug}/runs/{runId} Get a run with full result breakdown

curl

curl https://my.testnova.app/api/testnova/projects/my-web-app/runs/run_01... \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

📊 Reports & Bugs

Download PDF reports, trigger report emails, and query the bug log surfaced from failing runs.

GET /api/testnova/projects/{slug}/runs/{runId}/pdf Download the run report as a PDF

curl

curl https://my.testnova.app/api/testnova/projects/my-web-app/runs/run_01.../pdf \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY" \
  --output report.pdf

Returns a application/pdf stream — pipe directly to a file or S3.

POST /api/testnova/projects/{slug}/report-email Send the run report by email to project recipients

Request body

Field	Type	Description
runIdrequired	string	Run ID to send the report for

curl

curl -X POST https://my.testnova.app/api/testnova/projects/my-web-app/report-email \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "runId": "run_01..." }'

GET /api/testnova/bugs List bugs surfaced from failing runs

Query parameters

Parameter	Type	Description
projectSlugoptional	string	Filter by project
statusoptional	string	`open` \| `resolved` \| `ignored`

curl

curl "https://my.testnova.app/api/testnova/bugs?projectSlug=my-web-app&status=open" \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

🩹 Self-Heal

Trigger AI-powered self-healing for a project. Testnova re-snapshots the live app, detects selector drift, and regenerates failing scripts automatically.

POST /api/testnova/projects/{slug}/self-heal Re-snapshot & regenerate failing scripts

curl

curl -X POST https://my.testnova.app/api/testnova/projects/my-web-app/self-heal \
  -H "Authorization: Bearer tn_live_YOUR_API_KEY"

response

{
  "ok":      true,
  "healed":  3,
  "message": "3 scripts updated — re-run to verify"
}

💚 Health Check

No authentication required. Use this in uptime monitors and CI readiness probes.

GET /api/health Returns service status, region, and build commit

curl

curl https://api.testnova.app/api/health

response

{
  "status":    "ok",
  "service":   "@satumm/api",
  "region":    "sin1",
  "commit":    "a3f9c12",
  "timestamp": "2026-06-06T12:00:00Z"
}

Testnova REST API

Bearer token

Key format