TestDino API Conventions

Every endpoint in the TestDino Public API follows the same conventions for authentication, response shape, errors, and pagination.

Quick reference

Topic	Summary
Authentication	Bearer PAT (`td_pat_` prefix) scoped to the project
Rate limits	100/min per token · 200/min per IP · 1/min for PDF
Response format	`{ success, data, pagination? }` or `{ success, error }`
Errors	Uniform error codes with human-readable messages
Pagination	`page` + `limit` query params, `pagination` in response
Date filtering	Endpoint-specific, see table below

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer td_pat_your_token_here

Requirement	Value
Token type	Personal access token (PAT)
Token prefix	`td_pat_`
Required access	The token must grant access to the project in the request URL
Header format	`Authorization: Bearer td_pat_...`
Storage	Environment variable, secret manager, never commit to source

Create a PAT from User Settings → Personal Access Tokens. A PAT carries no permission scopes: you grant it access to specific organizations and projects when you create it. See Generate API keys.

NoteTokens can be rotated or revoked from User Settings → Personal Access Tokens at any time. A revoked token stops working immediately and returns 401 TOKEN_REVOKED.

Rate limits

Scope	Limit	Window
Per token	100 requests	1 minute
Per IP (pre-auth)	200 requests	1 minute
PDF generation	1 request	1 minute (per 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.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

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.

Response format

Every successful response uses this envelope:

{
  "success": true,
  "data": { /* endpoint-specific payload */ },
  "pagination": { /* present on list endpoints only */ }
}

Every error response uses this envelope:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Field	Type	Description
`success`	boolean	`true` for 2xx responses, `false` otherwise
`data`	object or array	Endpoint payload (omitted on error)
`pagination`	object	Present on list endpoints, see Pagination
`error.code`	string	Stable machine-readable code, safe to branch on
`error.message`	string	Human-readable description, safe to log, not safe to parse

Errors

Branch your client on error.code, not HTTP status alone. Codes are stable; messages may change.

HTTP	Error code	When it happens	Action
400	`VALIDATION_ERROR`	Missing or invalid query/path parameter	Fix the request, don’t retry
401	`UNAUTHORIZED`	Header missing, wrong prefix, or token not recognized	Fix the header, re-issue the token
401	`TOKEN_REVOKED`	The token was revoked	Create a new token
401	`TOKEN_EXPIRED`	The token passed its expiry date	Create a new token
404	`NOT_FOUND`	Resource doesn’t exist or isn’t accessible to this token	Verify the ID, confirm the token covers the project
429	`RATE_LIMIT_EXCEEDED`	Too many requests in the window	Back off using `RateLimit-Reset` / `Retry-After`
5xx	`INTERNAL_ERROR`	Server-side failure	Retry with exponential backoff

TipRetry only on 429 and 5xx. Use exponential backoff starting at 1 second, capped at 30 seconds, with jitter. Never retry 400, 401, 403, or 404.

Pagination

List endpoints accept page and limit. limit is not an arbitrary 1–100 range. Most run/analytics lists only accept 10, 25, 50, or 100 (default 10). Sending 20 returns 400 INVALID_LIMIT:

Parameter	Type	Default	Range
`page`	integer	1	≥ 1
`limit`	integer	10 (runs) / endpoint-specific	Runs & most DH lists: `10` \| `25` \| `50` \| `100`. Explorer: `10` \| `25` \| `50`. See each endpoint.

Pagination metadata is included in the response:

{
  "success": true,
  "data": [ /* items for this page */ ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 134,
    "hasNext": true,
    "hasPrev": false
  }
}

Iterate all pages in Node.js:

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.

Date filtering

There is no global date-filter convention. Each endpoint documents its own parameters:

Endpoint family	Parameter	Allowed values
Test runs list	`start_date`, `end_date`	RFC3339 timestamps, both required together
Explorer, specs, analytics	`days`	Integer snapped to 7, 30, or 90
Dashboard, filters	—	No query params (fixed downstream snapshot)

Test runs do not accept period, dateRange, or camelCase startDate/endDate. Use snake_case start_date/end_date. Rolling windows (days on explorer/specs/analytics): values other than 7, 30, or 90 are snapped to the nearest allowed window (default 30 when absent or invalid). String presets like dateRange=7d are not supported on analytics. Pass days=7 instead.

NoteSending undocumented query keys on public routes is stripped at the gateway, not forwarded silently. Check each endpoint’s reference page for the exact allowlist.

Introduction

Token Info

Test Runs

Test Cases

Context

Specs

Test Case Explorer

Dashboard

Analytics

Manual Tests

Reports

Filters

Usage

Token Info

Test Runs

Test Cases

Context

Specs

Manual Tests

Test Case Explorer

Dashboard

Filters

Reports

Analytics

Usage

Quick reference

Authentication

Rate limits

Response format

Errors

Date filtering

​Quick reference

​Authentication

​Rate limits

​Response format

​Errors

​Pagination

​Date filtering

Quick reference

Authentication

Rate limits

Response format

Errors

Pagination

Date filtering