Upload results with the API

To upload test results to Qualflare without the qf CLI, send them as JSON to POST https://api.qualflare.com/api/v1/collect with a project access token; each request creates one launch and returns its number.

Endpoints

Upload a launch

Send the whole run as one JSON body.

POST /api/v1/collect

Needs a project access token whose creator has the Editor role or higher in the project.

curl -sS -X POST "https://api.qualflare.com/api/v1/collect" \
  -H "Authorization: Bearer $QF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @launch.json

Returns 201: The launch number as {"seq": <n>}, and Location: /api/v1/launch/<n>.

{ "seq": 128 }

One request is one launch: put every suite of the run in suites. Qualflare finds each suite by name and creates the ones it doesn't have; inside a suite it matches each case to an existing test case by name, and creates new ones as Active, automated cases. See How uploads become test cases.

Request body

This body names the run, the environment and one suite with two cases. duration is in nanoseconds.

{
  "framework": "playwright",
  "platform": "web",
  "os": "linux",
  "environment": "development",
  "language": "en-US",
  "branch": "main",
  "commit": "9fceb02",
  "suites": [
    {
      "name": "Checkout",
      "duration": 4200000000,
      "cases": [
        { "id": "checkout-pays-by-card", "name": "pays by card", "status": "passed", "duration": 1800000000 },
        { "id": "checkout-applies-coupon", "name": "applies a coupon", "status": "failed", "duration": 2400000000, "error": "Expected total 90, got 100" }
      ]
    }
  ]
}

To see the body qf would send for your own reports, run qf <identifier> collect <files> --dry-run --output json.

Launch fields

Suite fields

Case fields

Attachments, steps, attempts, labels and links

List every attempt of a case in attempts, the final one last: fewer than 2 save nothing, and more than 50 keep the first 49 and the last.

Shortened, not refused

Some fields over their limit are shortened and the rest of the upload is saved; the limits that refuse an upload and the ones that cut it are in Results in one upload.

Retry safely with Idempotency-Key

Send an Idempotency-Key header with a value you generate once per upload, such as a UUID, and reuse it on every retry of that upload. A retry with the same key answers with the first launch's number and creates nothing: it isn't counted against your plan's launches again, and it sends no second webhook. qf does this for you.

KEY=$(uuidgen)
curl -sS -X POST "https://api.qualflare.com/api/v1/collect" \
  -H "Authorization: Bearer $QF_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" --data-binary @launch.json

Upload a CTRF report

Send the CTRF JSON file as the body and the launch's metadata in the query string.

POST /api/v1/collect/ctrf

Needs a project access token whose creator has the Editor role or higher in the project.

curl -sS -X POST "https://api.qualflare.com/api/v1/collect/ctrf?environment=staging&branch=main" \
  -H "Authorization: Bearer $QF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @ctrf-report.json

Returns 201: The launch number and warnings.

When the query leaves out the platform, language, browser, milestone or a CI field, a report exported from Qualflare fills it from its own qualflare.* block first. The environment comes only from the query, the report's testEnvironment or development.

The answer adds warnings, up to 20, each with a path and a reason: an environment Qualflare fell back from, a buildUrl it dropped, a summary count that doesn't match the tests, or a screenshot it dropped or kept as a reference.

{
  "seq": 129,
  "warnings": [
    { "path": "results.environment.testEnvironment", "reason": "environment \"staging-eu\" does not exist in this project; recorded against \"development\" instead" }
  ]
}

A report over the upload limits is cut to them without a warning.

For how statuses, suites and environments map, see Send CTRF reports.

Upload a large attachment

A file you upload through POST /api/v1/attachments/upload-url can be up to 50 MB: an MP4, WebM or QuickTime video, a ZIP file such as a Playwright trace, or a PNG, JPEG or GIF image. Its upload URL works for 5 minutes. (Rate limits and request sizes)

1. Ask for an upload URL:

   POST /api/v1/attachments/upload-url

   Needs a project access token whose creator has the Editor role or higher in the project.

   Name	Type	Default	Required	Description
   filename	body, string		Yes	The file's name, up to 255 characters, with no path; its extension must match mimeType
   mimeType	body, string		Yes	video/mp4, video/webm, video/quicktime, application/zip, image/png, image/jpeg or image/gif
   fileSize	body, integer		Yes	The file's size, 1 to 52,428,800 bytes

   curl -sS -X POST "https://api.qualflare.com/api/v1/attachments/upload-url" \
     -H "Authorization: Bearer $QF_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"filename": "checkout.mp4", "mimeType": "video/mp4", "fileSize": 1048576}'

   Returns 201: storageKey and uploadUrl.

   { "storageKey": "case-run-attachments/<project>/<file>.mp4", "uploadUrl": "https://…" }

2. PUT the file's bytes to uploadUrl within 5 minutes, with Content-Type set to the same mimeType and no Authorization header:

   curl -sS -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" \
     --data-binary @checkout.mp4

3. In the case's attachments, reference the file by storageKey, with its fileSize in bytes:

   { "name": "checkout.mp4", "mimeType": "video/mp4", "storageKey": "<storageKey>", "fileSize": 1048576 }

Uploaded files are kept as Data retention describes.

What happens after an upload

Qualflare saves the launch, then, in the background, sends the launch.completed webhook and your integrations' messages, adds the launch to the project's public report when it is published, and, when your plan includes them and AI is on for the project, groups its failures into failure clusters and starts the AI launch analysis. A retry with the same Idempotency-Key does none of this again.

Errors

Every status and code: Errors and status codes.

CLI and MCP equivalents

qf <identifier> collect builds this body from your report files and sends it with an Idempotency-Key (Upload results with qf collect). MCP has no upload tool (MCP server reference).

Related

• Guides: Send CTRF reports · Upload screenshots, videos and traces
• Reference: Launches · Rate limits and request sizes
• CLI/API: Qualflare API · Access Tokens