Skip to main content
Testorim is a single-origin application: the app, the HTTP API and the WebSocket used for live runs all serve from https://app.testorim.com.

​
The API surface

The API-key surface is small and deliberately so. It covers what a pipeline, a terminal or an integration needs: Full detail, including every response field, is in the API reference.
The API is unversioned in the URL. There is no /v1 prefix. The 1.0.0 in the reference is a documentation version, not a server version.

​
Scoping

An API key is bound to one user and one workspace, the one it was created in. Every request pins the workspace to the key’s, so a key issued for workspace A can never read or write workspace B, even if the owning person belongs to both. If that person is later removed from the workspace, the key stops working. Every list and lookup is workspace-scoped. A resource in another workspace returns 404, never 403. When the key’s owner belongs to the workspace that holds it, the 404 carries code: "other_workspace" with that workspace’s orgId and orgName. A key can make only these changes: trigger a run, cancel a run or a batch, create a project, and revoke a key. Any other change answers 403 with code: "api_key_scope". A key held by someone with the viewer role cannot make any change: it gets 403 with code: "read_only_role".

​
Rate limits

A throttled request returns 429 with { "error": …, "retryAfter": <seconds> } and a Retry-After header. There are no X-RateLimit-* headers, so do not write a client that depends on them. Rate limits are separate from plan limits. A spent allowance returns 429 with code: "plan_quota_exhausted", and a plan whose concurrent runs are all in use returns 429 with code: "concurrency_limit". Neither carries Retry-After. See Errors and Plans and limits.

​
Request rules

  • JSON bodies are capped at 1 MB.
  • Any string containing a NUL byte rejects the whole request with 400.
  • Schema failures return 400 with an issues array naming each problem.

​
Starting a run

POST /api/runs/trigger responds 202 Accepted with a run id. It does not wait for the run. Poll GET /api/runs/{id} until the status is terminal, or let the CLI do it for you. A run can wait for a browser after it is accepted. When every test browser is busy it waits in line; if none frees up in time it ends cancelled with the reason in its report. A cancelled run has no verdict.

​
What the API does not do

  • No outbound webhooks. Testorim will not call your server when a run finishes. Trigger the run yourself and read the result.
  • No streaming over HTTP. Live screenshots go over the app’s WebSocket, which is session-authenticated and not part of the API-key surface.
  • No billing, workspace, settings or integration management. Those are app-only, and a key is refused for them.