All endpoints require a Bearer token in the Authorization header:
Authorization: Bearer tdp_your_token_here
Requirement
Value
Token type
Project PAT (scoped to a single project)
Token prefix
tdp_
Required scope
public-api
Header format
Authorization: Bearer tdp_...
Storage
Environment variable, secret manager — never commit to source
Generate a Project PAT with the public-api scope via Generate API keys to access TestDino’s public-facing APIs. The PAT’s project must match the {projectId} in every request URL, otherwise you’ll get a 403.
NoteTokens can be rotated or revoked from Project Settings → API Keys at any time. A revoked token stops working immediately and returns 401 AUTH_INVALID_TOKEN.
Every response includes standard rate-limit headers:
Header
Meaning
RateLimit-Limit
Max requests allowed in the current window
RateLimit-Remaining
Requests remaining in the window
RateLimit-Reset
Seconds until the window resets
When you exceed a limit, the API returns 429 RATE_LIMIT_EXCEEDED. PDF-specific 429 responses also include a Retry-After header indicating how many seconds to wait.
TipFor batch work, back off to 1 request/second (60/min) to leave headroom. If you need more, throttle on RateLimit-Remaining and pause when it drops below 10.
let page = 1;const all = [];while (true) { const res = await fetch( `${BASE_URL}/${projectId}/test-runs?page=${page}&limit=100`, { headers: { Authorization: `Bearer ${token}` } } ); const body = await res.json(); all.push(...body.data); if (!body.pagination.hasNext) break; page += 1;}
NoteA few endpoints use offset + limit instead of page + limit (e.g. GET /test-cases/history). The parameter name is documented on each endpoint’s reference page.
Endpoints that filter by time accept either a predefined range or a custom range. The preset parameter name depends on the endpoint: most use dateRange, the test runs list uses period. Both take the same preset values and behave identically.
If both the preset and startDate/endDate are provided, the preset takes precedence and the custom dates are ignored. Pick one:
If you want…
Send
Don’t send
Preset range
dateRange=30d or period=30d
startDate, endDate
Custom range
startDate=..., endDate=...
dateRange, period
NotestartDate and endDate must be sent together. Sending only one is treated as invalid. Check each endpoint’s reference page for which preset parameter it accepts.
Some detail endpoints return a lean payload by default and expose heavier sections — errors, coverage, specs, artifacts, history — behind an opt-in ?include= parameter. This keeps default responses fast and predictable.Pass a comma-separated list of the sections you need, or all for everything the endpoint supports. Bundling exactly the data your view renders into a single round-trip avoids chaining follow-up requests from the client.
GET /{projectId}/test-runs/{runId}?include=errors,coverageGET /{projectId}/test-runs/{runId}?include=all
include=history on /test-cases/{caseId} enables a second pagination for the history list, separate from any list-endpoint pagination. Three parameters control it, and all are ignored unless include=history (or include=all) is set:
Parameter
Default
Description
historyPage
1
Page number within the history list (integer, ≥ 1).
historyLimit
20
Items per history page (integer, 1–100).
historyStatus
—
Filter by outcome: passed, failed, flaky, or skipped.
TipRequest only what you’ll render. include=all is convenient for exploration, but on production dashboards narrow it to the sections you actually display — smaller payloads, faster responses.
