API Access & CI/CD Keys

Automate your visual testing workflows by integrating retestr.ai directly into your CI/CD pipelines using API Keys.

Why use API Keys?

While you can log in to the dashboard with your email/password or social account, automated systems (like GitHub Actions, Jenkins, or scripts) need a secure way to authenticate without user interaction.

API Keys allow you to:

• Trigger Test Runs: Start a visual regression suite from your CI pipeline.
• Fetch Results: Poll the API to check if a run passed or failed.
• Manage Baselines: Programmatically approve baselines (advanced usage).
• Audit Usage: Track exactly which system performed an action via Audit Logs.

Creating an API Key

API Keys are scoped to an Organization. Only Organization Admins can create and manage them.

1. Navigate to Settings > API Keys.
2. Click Create New Key.
3. Name: Give your key a descriptive name (e.g., "GitHub Actions CI", "Nightly Cron Job").
4. Scopes: Select the permissions this key requires.
   • run:read: View test runs and results.
   • run:write: Trigger new test runs (Most common for CI).
   • project:read: List projects.
   • baseline:read: Fetch baseline images.
   • admin:write: Full administrative access. Use with caution.
5. Expiration: (Optional) Set an expiry date for the key. We recommend rotating keys periodically.
6. Copy the Key: The full key (starting with vts_) will be shown only once. Copy it immediately and store it securely (e.g., in GitHub Secrets).

Using API Keys

Pass your API Key in the Authorization header as a Bearer token for all requests to https://retestr.ai/api.

Example: Cancel All Runs (Global Panic)

If you need to halt all test execution programmatically, you can use the Global Panic endpoint. This will immediately cancel all PENDING and RUNNING jobs for your organization.

curl -X POST https://retestr.ai/api/runs/cancel-all \
  -H "Authorization: Bearer vts_YOUR_API_KEY_HERE"

Example: Trigger a Run (cURL)

curl -X POST https://retestr.ai/api/runs \
  -H "Authorization: Bearer vts_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "YOUR_PROJECT_ID",
    "branch": "main",
    "commitSha": "OPTIONAL_COMMIT_SHA"
  }'

Example: GitHub Actions

You can use our official action or a simple curl step in your workflow.

1. Add RETESTR_API_KEY to your repository secrets.
2. Add RETESTR_PROJECT_ID to your repository variables (or secrets).

name: Visual Regression

on: [push]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Retestr Run
        run: |
          curl -X POST https://retestr.ai/api/runs \
            -H "Authorization: Bearer ${{ secrets.RETESTR_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "projectId": "${{ vars.RETESTR_PROJECT_ID }}",
              "branch": "${{ github.ref_name }}",
              "commitSha": "${{ github.sha }}"
            }'

API Key Usage Metrics

To help you monitor and audit your automated systems, retestr.ai tracks the usage of each API Key.

On the Settings > API Keys page, you can view:

• Last Used Date: The exact timestamp of the last successful request made with the key.
• Request Count: The total number of requests made using the key over its lifetime.

This visibility helps you identify unused, stale, or overactive keys, making it easier to confidently rotate or revoke credentials without breaking active integrations.

Revoking Keys

If a key is compromised or no longer needed:

1. Go to Settings > API Keys.
2. Find the key in the list.
3. Click the Trash Icon (Delete).
4. The key will be immediately invalidated, and any scripts using it will fail with 401 Unauthorized.