Quickstart
Create an API key, start a run, wait for it and read the verdict, in about five minutes.
You need an Outqube organisation with an app that has at least one test in a suite. The examples use a suite named smoke.
Create an API key
An organisation admin opens Settings, API keys and selects Create API key. Give the key a name, pick the app, pick the scope trigger (it can start runs and read results) and choose when it expires. Copy the key. You see it once.
Keep it in an environment variable. In CI, store it as the secret OUTQUBE_API_KEY.
export OUTQUBE_API_KEY=oq_...Start a run
POST /runs takes exactly one of suite, test_ids or tag. The call returns at once with the run in the queued state.
curl -X POST https://app.outqube.com/api/v1/runs \
-H "Authorization: Bearer $OUTQUBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "suite": "smoke", "base_url": "https://staging.example.com" }'The response has the run id, its status and a url that opens the run in the dashboard. Leave base_url out to test the environment's own URL.
Wait for the result
Poll GET /runs/{runId} until status is completed or cancelled. Every few seconds is well within the rate limit. Or let Outqube call you: add an event webhook and wait for run.completed.
let current = run;
while (current.status === "queued" || current.status === "running") {
await new Promise((resolve) => setTimeout(resolve, 5000));
const poll = await fetch(`${API}/runs/${run.id}`, { headers });
if (!poll.ok) throw new Error(`Outqube answered ${poll.status}`);
current = await poll.json();
}The CLI does this for you when you pass --wait.
Read the verdict
When the run is completed, outcome is passed, failed or error. error means something other than a verdict on your app, such as a timeout or a test that could not finish. Treat any value you do not know as not passed.
console.log(current.outcome, current.counts);
for (const test of current.tests) {
if (test.outcome !== "passed") {
const report = await fetch(
`${API}/runs/${run.id}/tests/${test.test_run_id}/report`,
{ headers },
).then((r) => r.json());
console.log(test.name, report.markdown ?? report.status);
}
}A report is written once a test fails or errors. While it is being written the answer has status: "pending", so ask again a few seconds later.
Next steps
- Core concepts: what runs, suites, environments and results are.
- Run Outqube from CI: fail a job when a test fails.
- Receive and verify webhooks: get told when a run finishes instead of polling.
Introduction
Outqube tests your web app in a real browser and records proof of every step. Start runs from CI, get notified when they finish and connect your coding agent.
Authentication
Create an API key, choose its scope, keep it safe and rotate it. The same key works for the API, the CLI and the MCP server.