REST API
The TestVibe REST API (/api/v1/ops/*) exposes supported operations for projects, features, groups, generation, runs, results, load tests, coverage, and more. Consult the endpoint reference for the available surface; some settings and UI workflows are not public API operations. The same API powers the testvibe CLI, the MCP server for AI tools, and the in-app Assistant's own tool calls, so all three stay in sync with what the API can do.
Call the API with a bearer key, see what a rate limit looks like, install the testvibe CLI, and gate a pipeline on --wait, --timeout, and the exit code.
Full endpoint documentation, request/response shapes, and examples.
Create a tvb_… key in Settings → CLI & API keys.
Authentication
Every request carries a bearer key created in Settings → CLI & API keys:
Authorization: Bearer tvb_...
A key belongs to the workspace where it was created and acts as its creating user. Workspace/project authorization and role checks still apply. Revoke a key from the same panel if a machine is retired or a key may have leaked — see CLI & API keys.
Rate Limits
Requests to the ops API (and therefore the CLI and MCP server, which are HTTP clients of it) are token-bucket limited:
| Bucket | Default limit | Notes |
|---|---|---|
| Per workspace | Team: 1,000/hour; Business: 5,000/hour; Enterprise: unlimited plan bucket | Shared across keys. Free and Personal do not include operations API access (403). |
| Per IP | 10,000 requests/hour | Applied before key validation, so an invalid-key flood can't be used to probe or overload the API. |
Exceeding a limit returns 429 Too Many Requests with a Retry-After header. Self-hosted instances bypass the cloud plan entitlement but can retain operator-configured rate limits. The IP bucket remains independent of the plan bucket.
The testvibe CLI And MCP Server
The testvibe CLI and its MCP stdio server (for Claude Desktop/Code, Codex, and similar AI tools) wrap the same authenticated API — install once, then use the CLI directly or point an AI tool at the MCP server.
Install it from the npm registry:
npm install -g testvibe
No npm? Settings → CLI & API keys also shows npm-free commands that download and set up the CLI directly from your TestVibe server.
Waiting For A Run, And What The Exit Code Means
Commands that dispatch work — run, verify, load run, coverage scan, coverage run, and generate — return as soon as the work is queued. Add --wait (--watch on generate) to hold on until it actually finishes, which is what makes the CLI usable as a CI gate:
testvibe run --all --url https://staging.example.com --wait --timeout 1800
--timeout <seconds> is the ceiling on that wait. It is one budget for the whole command — a suite of 19 features waits at most that long in total, not 19 times over — so a run stuck waiting for capacity can never hang your pipeline. It defaults to 5400 seconds (90 minutes), can be set with the TESTVIBE_WAIT_TIMEOUT_SECONDS environment variable, and --timeout 0 waits indefinitely.
The exit code tells you which of four things happened:
| Exit code | Meaning |
|---|---|
0 | Everything finished and passed. |
1 | It finished and something actually failed — this is the one your build should go red on. |
2 | A generation stopped to ask you a question. It needs a person, nothing is broken. |
3 | The wait ended without an answer: the timeout elapsed, or the CLI lost contact with the server. No verdict — the work may well still be running, and this never means your tests failed. |
Keep 3 distinct from 1 in your pipeline. Once a red build can also mean "we stopped watching", a red build stops meaning anything.
Full details, including which commands accept --timeout: the CLI wait contract and Run TestVibe in CI.
Related Help
- CLI & API keys
- REST API reference
- The testvibe CLI — every command, its flags, and the wait contract.
- Run TestVibe in CI