Skip to content

Testpad API (1.0)

Welcome to the reference manual for the Testpad API.

This manual assumes you know what Testpad is, how the user interface works, and most importantly, what everything is called.


Initial Access

Please note, for now:

  • the API feature has to be enabled, by Testpad Support, to be able to access it at all
  • only account “owner” users can configure API access (i.e. issue access tokens)

An Evolving API

The API is brand new for Testpad and will be updated in response to feedback from customers.

Please see the Change Log for information on what might have changed since you last looked.

Please also see the Unsupported Capabilities section for some discussion of what can't be done yet.

And if you have a scenario or use-case in mind for the API that is not yet supported, please email support@testpad.com.


Mostly RESTful

The API mostly conforms to RESTful principles.

  • HTTP GET requests are used to retrieve information.
  • HTTP POST requests are used for actions like creating new folders, scripts, tests and test runs, where the server will generally be inventing new IDs for these objects and returning them in the response payload.
  • HTTP PATCH requests are used for modifying parts of existing objects, supplying new (replacement) values for a subset of the keys of those objects.
  • Testpad does not currently support HTTP PUT requests – the wholesale replacement of objects with a new object.
  • Testpad does not currently support HTTP DELETE requests – these are likely to be supported in the future, but we are protecting you and ourselves from accidental data loss for the time being.

To do something with Testpad's API, you need to send a request to one of the API endpoints. These are the URL path that the request is being directed to, and should be thought of as sending a message to the relevant 'owning' object.

For example, a GET request to /projects/ is to fetch data on all projects.

Or, a POST request to /projects/:p/folders is a create action on that project’s collection of folders, i.e. to create a new folder in the list of folders.

API Server


HTTPS only

The API only responds to requests sent securely using HTTPS.

Clients must validate SSL/TLS certificates (including the certificate chain and hostname) to ensure they are communicating with Testpad. Failure to properly validate the certificate exposes your integration to man-in-the-middle attacks, where malicious actors could intercept, modify, or steal your data.


Domain

Find the API Server at https://api.testpad.com.

Note the subdomain is api and not your account ID.


Paths

All API endpoints are hosted on paths that begin with the common prefix /api/v1/.

At some point in the future, if backwards incompatible changes are introduced, these will be introduced at a new version number, e.g. /api/v2/.

However, in general, every attempt will be made to keep changes and new features backwards compatible, and while this holds true, the API will continue to be hosted at /api/v1/.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://api.testpad.com/api/v1/

Authentication

All requests to the Testpad API must include the Authorization HTTP Header that supplies an API access token for your account.


HTTP Header

The Authorization header value must have the format: Authorization: apikey <TOKEN>

The token must be preceded by the prefix apikey to be considered a valid authorization value. It is envisaged that alternative authorization schemes may be added in the future, and these would be differentiated with a different prefix.


API Access Token

Create and manage API Access Tokens on the API settings page in the Testpad app (account Owners only).

The API settings page is found in the Settings section of the navigation links in the bottom left of the main project view.

If you cannot see a link to API settings (and you are an Owner-type user), then your account probably has not yet been enabled for API access – please contact support@testpad.com to request access.

Security notes:

  • Tokens are 3072-bit random numbers encoded as a 48-character case-sensitive string.
  • Tokens are generated by Testpad using a cryptographically-strong random number generator.
  • An account may generate and make use of multiple tokens, e.g. to give different teams different tokens.
  • For now, the API is secured with tokens that grant access to all API capabilities and across all projects. It is expected that more fine-grained control such as role-specific and project-specific access keys will be supported in the future.

◉ Project Endpoints

Operations

◉ Folder Endpoints

Operations

◉ Script Endpoints

Operations

◉ Run Endpoints

Operations

◉ Note Endpoints

Operations

Common URL Parameters


Multiple endpoints are available for retrieving folders and scripts, and their responses can contain substantial amounts of data. To help clients request only the information they need, these endpoints support a common set of URL parameters.

If not supplied in requests, default values for these parameters will be assumed. Note that the defaults used vary depending on whether the request is for a single script object or a folder of several script objects.


subfolders (enum)

Controls whether the nested contents of a retrieved folder should also be retrieved.
Only applicable to endpoints retrieving folder items.

  • none – the contents of any subfolders in the target folder are not included
  • all - (default) – the contents, and recursively nested contents, of a retrieved folder are included

scripts (enum)

Controls how much of the script meta data to include (e.g., description, report comments, creation date).

  • terse (default for folder endpoints) – only includes the script’s name and ID
  • full (default for script endpoints) – adds all the basic information about the script, including description, creation date, report comments, and whether the script is archived.

This parameter does not affect inclusion of tests, fields, runs, or results.


tests (enum)

Controls whether or not (and in which format) the tests of a script are included in the tests field of script objects.

  • none (default for folder endpoints) – excludes the tests field entirely
  • full (default for script endpoints) – includes tests as a list of objects with fields: id, indent, text, and tags
  • list – includes tests as a list of strings, with leading whitespace to show indentation
  • text – includes tests as a single string, with each test separated by newlines and indentation preserved

testswith (list of enum)

Modifies how tests are returned when tests are included. Most useful when formatting tests as lists or long strings.

Combine multiple values with commas (e.g., testswith=hashtags,ids).

  • none (default) – test text is included as is, without decoration
  • hashtags – includes tags as Twitter-style hashtags appended to each test text string. If tests are being returned as objects, the tags field is omitted.
  • ids – prefixes each test text string with the test ID. Ignored if tests are objects.
  • _ids – same as ids, but right-aligns ID numbers (4 digits wide). Ignored if tests are objects.

fields (enum)

Controls the contents of the fields field of script objects.

This field defines the set of headers available for each run header (e.g., run number, tag filters, custom fields etc).

  • none (default for folder endpoints) – field information is not returned
  • full (default for script endpoints) – fields are defined as a list of objects with:
    • id
    • label
    • shown (boolean)
  • list – fields are returned as a simple list of all labels in use
  • list_shown – same as list, but only includes fields marked as shown

runs (enum)

Controls how test run data is included in the runs field of script objects.

  • none (default for folder endpoints) – data on the test runs are not included
  • full (default for script endpoints) – script objects will contain full run definitions, including state, tester, and header values, but not results (which depend on the results parameter below)
  • terse – returns a brief summary of each test run (one-line string label summarizing header values and run number)

retests (enum)

Controls whether to include old (superseded) test runs.

  • latest (default) – only the latest retest of each run is returned
  • all – includes all test run data, including superseded runs

results (enum)

Controls whether results data is included in the response (but only if the runs field is being included).

Results are included as the results field inside run objects (nested in runs).

  • none (default for folder endpoints) – the results field is excluded from run objects
  • full (default for script endpoints) – results are included as a list of result objects, with fields:
    • result (e.g., pass, fail, query, blocked)
    • comments - string
    • issues - string

Only non-empty result objects are included.


progress (enum)

"total": 4, "pass": 1, "fail": 3, "block": 0, "query": 0,

Controls how progress statistics are included in the progress field of folders, scripts, and runs.

  • none (default for folder endpoints) – progress fields are excluded
  • terse (default for script endpoints) – progress fields are included and contain:
    • total - integer - the number of tests that have a result value recorded, i.e. the total tried so far
    • pass - integer - the count of results marked as pass
    • fail - integer - the count of results marked as fail
    • block - integer - the count of results marked as blocked
    • query - integer - the count of results marked as queried
    • summary: a human-readable summary string of these counts
  • full – returns progress as an object with individual count fields as well as percentage values. The percentage values are rounded to the nearest integer, set to be at least 1% if >0, and adjusted to all sum to 100% (thus making them useful for e.g. CSS %width values in a dashboard display).

Supplying Test Text

Test text can be provided as part of creating new scripts via these endpoints:

  • POST /projects/:p/scripts — create a script in a project
  • POST /projects/:p/folders/:f/scripts — create a script in a folder

Choice of format:

  • As a string: a block of text with a test per line
  • As a list of strings: a test per item in the list
  • As a list of objects: a test per item in the list, with fields such as id, text, indent, tags, notes, results

Key details:

  • When supplying tests as a string or list of strings, IDs cannot be specified.
  • Indentation can be inferred from leading whitespace (when indent is not supplied).
  • Tags can be supplied using hashtags at the end of the test.
  • Multiline cells are supported in list of strings (via \n), but not supported when supplying tests as a single string.
  • Results can be supplied per-test when using the list of objects format.

Supplying Test Runs

Test runs (columns) can be created using several endpoints:

  • POST /projects/:p/scripts — create a script in a project, including one or more test runs
  • POST /projects/:p/folders/:f/scripts — create a script in a folder, including one or more test runs
  • POST /scripts/:s/runs — add a single test run to a script

Where multiple test runs are being supplied (the create new script endpoints), the runs field will be a list of the run objects.
Where a single test run is being supplied (the add a single test run endpoint), the payload is a single test run object.

Test Run object (fields):

  • id (optional)
  • headers (optional)
  • completed (boolean or "auto") (optional)
  • results (object) (optional)

Notes:

  • The ID can only be supplied when creating scripts. Once a script exists, new IDs will be created for you by Testpad.
  • Built-in header fields are read-only (_run, _createdDate, _createdTime).
  • Any header fields that do not receive a value will be left empty.
  • Any header field values supplied in the test run that do not exist in the script will be ignored.

Supplying Test Results

Test results can be provided to Testpad as part of creating Scripts using these endpoints:

  • POST /projects/:p/scripts
  • POST /projects/:p/folders/:f/scripts

Results can be provided either together with a test row (per row), together with a test run column (per column), or individually.

Per-row (in test objects):

  • results as a list maps in order to the defined test runs.
  • results as an object uses test run IDs as keys.

Per-column (in run objects):

  • results is an object with test IDs as keys.

Individual result formats:

  • String: "pass", "fail", "blocked", "exclude", "query"
  • List: [result, comment, issue] (triple)
  • Object: { "result": "...", "comment": "...", "issue": "..." }

Progress Objects

Test result statistics for test runs, scripts, folders and folders of folders, are represented as progress objects.

  • Terse: pass, fail, blocked, query, total, summary
  • Full: adds percentages (passPc, failPc, etc.), tried, remain, and counts

The percentages are rounded to the nearest integer, adjusted to be at least 1 when non-zero, and such that they always sum to 100.

Error Handling

During development of client code (code that makes requests to the Testpad API), it is recommended to catch all errors and to print their details out to the console or a log file for inspection of what went wrong.

Once in production, client code might scale back on the verbosity of its error reporting, however, it should nevertheless always maintain specific handling for the following error conditions, which, in theory, could happen to any request:


401 Unauthorized

The error 401 Unauthorized will be returned if your access token does not have, or no longer has, the relevant permissions to access the API.


429 Too Many Requests

The error 429 Too Many Requests will be returned to any request that exceeds Testpad's rate limits. Please see Rate Limiting for details.

If your code receives this error, it must wait for the indicated amount of time before trying again.

Rate Limiting


The API protects itself from excessive load by limiting the rate at which received requests will be processed.

There are several types of rate limit applied, and requests must 'pass' all of these to be successful. I.e. if any one of these different rate limiters is triggered, then the request will be rejected.


Custom Limits

The default rate limits are defined below and are subject to change. For now, all subscription plans have the same limits, but this may well change in the future, with the larger plans obviously allowing for higher API usage requirements.

If you are finding your rate limits insufficient, please contact support@testpad.com to discuss what you are trying to do and the possibility of increasing these limits for your account.


Rejected Requests

Requests rejected for exceeding a rate limit will get a 429 TOO MANY REQUESTS response.

The response will contain the Retry-After HTTP header, specifying how many seconds until a repeat attempt will be successful.


Global (Load Balancer) Rate Limits

Testpad deploys two types of rate limiter, a global rate limiter that applies to all requests, along with several request-specific limiters that apply different rates for different types of request.

The global rate limit is 1000 requests per hour, which is an average of 1 request every 3 seconds, but allows for bursts of up to 100 requests at a time.

If 100 requests arrived back to back, then the client would have to wait 300 seconds before being able to continue (i.e. maintaining the average rate of 1000 requests per hour).


GET (Fetch) Rate Limits

For GET (fetch) requests, the API applies two rate limits:

  • 1GB of response data per day, and
  • a burst rate limit of 50MB every 3 minutes

Within any 3 minute period, Testpad will not respond if more than 50MB of data have already been returned.

And within any 24 hour period, Testpad will not respond if more than 1GB of data has already been returned.


POST (Write) Rate Limits

For POST (write) requests, the API applies limits to how many scripts and how many test runs can be created:

  • 500 new scripts per month, and

  • a burst limit of 100 scripts per hour


  • 1000 new test runs per month, and

  • a burst limit of 200 test runs per hour


How the Rate Limits work

Note – the following HTTP headers are not implemented yet, but we keep their documentation here as they help explain how the rate limiters are implemented.

Every API response contains rate limit status information as HTTP headers.

X-Testpad-Rate-Limit-Read — Present in responses to GET requests that are attempting to retrieve (read) information.

X-Testpad-Rate-Limit-Write — Present in responses to POST requests that are attempting to create information.


The value of these fields is a list of rate limiter names and their current statistics.
Examples:

fetch_daily[85.2% 893387 of 1048576 KB/day] — describing the rate limiter called 'fetch_daily' which has a current capacity of 893387 KB (how much more data it will allow through), out of a maximum capacity of 1048576 KB (1 GB) per day.

scripts_monthly[99.0% 493 of 500 scripts/month] — describing the rate limited called 'scripts_monthly' which has a current capacity of 493 scripts (how many new scripts it will permit), out of a maximum capacity for 500 new scripts per month.


Rate limiters will reject requests once its current capacity value goes below zero.
The current capacity of each rate limiter is continuously recharging. The value of `Retry-After` is the number of seconds until the capacity level of a rate limiter will go back above zero.

This means that clients do not have to wait e.g. a whole month before they can continue after a 429 error. Instead, they only need to wait until the capacity of the relevant rate limiter has recharged to a positive value again. However, do note that if a request is made immediately after a limiter's capacity has just returned positive, then that capacity is likely to immediately become negative again and thus block subsequent requests.

Change Log

[1.0.0] – 2025-11-01

General release of the Testpad API.

[0.9.0] - 2025-08-01

Pre-release for early adopter beta-testing.

Unsupported Capabilities

There are many possibilities for the future of Testpad's API. Here is a (obviously non-exhaustive) list of notable features that might be expected of the API but which are not supported for the time being.

  • Creating and Modifying Projects
    Projects cannot be created by the API and basic project information like names and descriptions cannot be modified. However, the contents of project (scripts and folders) can be modified via the several project and folder endpoints.

  • Folder manipulations
    Folder items (scripts, notes and nested folders) cannot be moved around. There's no support for moving folder items between folders or between projects.
    Similarly, there's no support yet for archiving or unarchiving scripts, notes and folders.

  • Script field set modifications
    The set of fields in a script cannot be modified by the API. Custom fields can be created as part of the creation of a new script, but once created, the API cannot modify the set of fields defined for a script.

  • Adding tests to scripts
    For now, the set of tests in a script can only be created at the time the script is created.

  • Deleting content
    For now, there is no provision for deleting content with the API. This is partly because most use-cases for the API will be about creating content to record new testing, but also to protect new API users from themselves until good safeguards against accidental delete operations have been devised. Suggestions welcome!

Support

For support, or if you have a scenario or use-case in mind for the API that is not yet supported, please email support@testpad.com.