> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testorim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The API-key surface: trigger runs, read results, and manage projects, saved tests and keys.

The Testorim HTTP API lets a pipeline, a terminal or an integration start test
runs and read their results.

<Card title="Authentication and API keys" icon="key" href="/developers/authentication">
  Mint a key, send it, and understand what it can reach.
</Card>

## Base URL

```text theme={null}
https://app.testorim.com
```

Every route mounts flat under `/api`. There is no version prefix.

## Authentication

An HTTP Bearer token on the `Authorization` header:

```bash theme={null}
curl https://app.testorim.com/api/me \
  -H "Authorization: Bearer tst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

A key is pinned to one workspace. Resources in another workspace return `404`,
not `403`.

## Starting a run

```bash theme={null}
curl -X POST https://app.testorim.com/api/runs/trigger \
  -H "Authorization: Bearer $TESTORIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"procedureId": "<procedure-id>"}'
```

The response is `202 Accepted` with a run id. Poll `GET /api/runs/{id}` until
the status is terminal, then read `overallStatus` for the verdict.

Ad-hoc runs take a `projectId` and a `description` instead of a
`procedureId`.

## Errors

| Status | Meaning                                                             |
| ------ | ------------------------------------------------------------------- |
| `400`  | Invalid body. An `issues` array names each problem                  |
| `401`  | Bad, revoked or expired credential                                  |
| `402`  | Payment required. The code names which limit and links to upgrade   |
| `403`  | `read_only_role`. A `viewer` key attempted a write                  |
| `404`  | Not found, or not in this key's workspace                           |
| `429`  | Rate-limited (with `Retry-After`) or plan quota exhausted (without) |
| `503`  | Capacity. The global concurrent-run cap, not your fault             |

## Scope

This reference documents the **API-key surface**. The app itself calls many
more endpoints: billing, provider webhooks, OAuth callbacks, fixtures,
environments, schedules, alerts, visual baselines, sharing, flakiness,
variables, performance budgets, role probes, workspace management. Those are
session-oriented or provider-signed and are deliberately not published as an
integration surface.

Testorim does not send outbound webhooks.


## Related topics

- [Platform overview](/developers/platform-overview.md)
- [Revoke an API key](/api-reference/api-keys/revoke-an-api-key.md)
- [List active API keys](/api-reference/api-keys/list-active-api-keys.md)
- [Mint a new API key (browser session only)](/api-reference/api-keys/mint-a-new-api-key-browser-session-only.md)
- [Cancel a single run](/api-reference/runs/cancel-a-single-run.md)