API & Automation

Proba.run exposes a machine-facing layer for CI pipelines and scripts: a public REST API for reading and writing your test data, dedicated endpoints for submitting automated test results, and one-way synchronization of test cases with a git repository. All of it is authenticated with an API key instead of a user session.

API keys

An API key is a project-scoped secret used for machine access — no login, no 2FA. Create one from your project settings, on the API keys tab.

1. Click New key and give it a name.
2. The raw key is shown exactly once, right after creation. Copy it immediately — Proba.run only stores a hash, so it cannot be shown again.
3. Send the key on every request in the X-Api-Key header.

Each key has a scope:

Use a read_only key wherever a script or integration only needs to read data (for example, the case sync skill described below). Revoke a key from the same tab at any time; revoked keys stop working immediately.

Public REST API

The public API lives under /api/v1/** and is scoped to the project the key belongs to — there is no project identifier in the URL, so a key can never reach another project's data.

List endpoints are paginated with ?page and ?perPage (default 25, maximum 100) and return { items, total, page, perPage, totalPages }. Any error responds with { "error": "...", "code": "..." } — branch your client logic on code (unauthorized, not_found, validation_failed, archived, rate_limited), not on the error text.

Example requests

List a project's active cases:

curl -H "X-Api-Key: qalab_xxx" \
  "https://your-instance.example.com/api/v1/cases?status=active&page=1"

Submit a result for a case in an existing run:

curl -X POST \
  -H "X-Api-Key: qalab_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"passed","elapsedSeconds":1.4}' \
  "https://your-instance.example.com/api/v1/runs/42/cases/DMO-17/results"

Submitting automated test results

For CI pipelines that just need to report results without managing runs case by case, use the automation endpoints. Both create a closed run in one call and auto-create any missing test case by title.

• POST /api/automation/runs — JSON body with a run name and a results array (title, status, optional elapsedSeconds/comment).
• POST /api/automation/runs/junit — multipart upload of a JUnit XML file plus a name field.

Both require X-Api-Key and return the created run, including its progress summary, so CI can link back to it.

Rate limits

Every machine endpoint is rate-limited per API key, with a 429 response and a Retry-After header when exceeded:

Syncing test cases with a git repository

Instance owners can link a project to a GitHub repository so test cases stored as markdown files stay in sync with Proba.run. This is aimed at teams that want Claude Code (or another tool working inside the repo) to read, review, and test against the same case files the team edits in Proba.run.

• Repository to Proba.run: from the project's Repository sync settings, configure the repo (owner, name, branch, path prefix) and a token, then click Synchronize. A preview shows what will be created, updated, moved, or unlinked before anything is written.
• Proba.run to repository: the /api/v1/sync/manifest endpoint returns the current state of every synced case as file content. A companion skill, installed into the repository, pulls this manifest and updates local files to match — creating, overwriting, moving, or removing files as needed. It never commits or pushes; that stays a manual, reviewed step.

A read_only API key is the recommended choice for the sync skill, since it only ever needs to read the manifest.