Skip to content
Gaffer Gaffer
Join Now Login

cURL Guide

This guide shows how to upload test reports to Gaffer using cURL from the command line. This is useful for quick uploads, debugging, or integrating with custom CI/CD systems.

Prerequisites

Section titled “Prerequisites”
  • A Gaffer account with a project
  • Your project’s upload token
  • cURL installed (available by default on macOS and most Linux distributions)

Basic Upload

Section titled “Basic Upload”

The simplest upload with just a file:

curl
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_UPLOAD_TOKEN" \
  -F "files=@path/to/test-report.html"

Replace YOUR_UPLOAD_TOKEN with your actual upload token, and update the file path to point to your test report.

Upload with Tags

Section titled “Upload with Tags”

Add metadata tags to help organize your test runs. We strongly recommend including commitSha and branch:

curl
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_UPLOAD_TOKEN" \
  -F "files=@playwright-report/index.html" \
  -F 'tags={"commitSha":"abc123def456","branch":"main","test_framework":"playwright","test_suite":"e2e"}'

Upload Multiple Files

Section titled “Upload Multiple Files”

Upload multiple files by repeating the -F "files=..." flag:

curl
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_UPLOAD_TOKEN" \
  -F "files=@playwright-report/index.html" \
  -F "files=@playwright-report/data/report.json" \
  -F "files=@playwright-report/screenshots/failed-test.png" \
  -F 'tags={"commitSha":"abc123","branch":"feature/login"}'

Dynamic Git Information

Section titled “Dynamic Git Information”

You can use shell command substitution to automatically include git information:

curl
curl -X POST https://app.gaffer.sh/api/upload \
  -H "X-API-Key: YOUR_UPLOAD_TOKEN" \
  -F "files=@test-results/junit.xml" \
  -F 'tags={"commitSha":"'"$(git rev-parse HEAD)"'","branch":"'"$(git branch --show-current)"'"}'

Common Issues

Section titled “Common Issues”

401 Unauthorized

Section titled “401 Unauthorized”

Check that your upload token is correct and properly formatted. The token should start with gfr_.

400 Bad Request - No files provided

Section titled “400 Bad Request - No files provided”

Ensure you’re using -F "files=@..." with the @ symbol before the file path. The @ tells cURL to read the file contents rather than using the path as a string value.

400 Bad Request - File too large

Section titled “400 Bad Request - File too large”

Individual files are limited to 50 MB, and total upload size is limited to 100 MB.

Next Steps

Section titled “Next Steps”