API Reference

Complete reference for the Euriqa REST API. Use the API to programmatically manage test runs, results, artifacts, projects, teams, and more.

Base URL

All API requests are made to the following base URL:

bash

https://app.euriqa.dev/api

All API communication requires HTTPS. HTTP requests will be rejected.

Authentication

Euriqa supports two authentication methods. Both enforce the same authorization rules.

API Key

Use an API key for CI/CD pipelines and programmatic access. Pass your key via the X-API-Key header.

API Key Authenticationbash

curl -X GET https://app.euriqa.dev/api/runs \
  -H "X-API-Key: your-api-key"

Session Cookie

Browser-based authentication uses a session cookie set during login. This is used automatically by the Euriqa dashboard.

Session Cookie Authenticationbash

curl -X GET https://app.euriqa.dev/api/runs \
  -H "Cookie: sb-access-token=your-session-token"

API keys are scoped to a specific project. Generate them from the project settings page in the dashboard.

Test Runs

Test runs represent a single execution of your test suite. Each run contains metadata about the CI environment, branch, commit, and aggregate test results.

Create a Test Run

POST /api/runs

Creates a new test run. Typically called at the start of a test suite execution.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "status": "running",
  "branch": "feature/login-flow",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "shardCurrent": 1,
  "shardTotal": 3,
  "browser": "chromium",
  "os": "linux",
  "viewport": "1280x720",
  "hostname": "ci-runner-01",
  "runTitle": "Login Flow Tests",
  "tags": ["smoke", "login"],
  "grepPatterns": ["@smoke"]
}

projectIdstringRequired
The project ID this run belongs to.
statusstringRequired
Initial run status. One of: running, passed, failed.
branchstring
Git branch name.
commitShastring
Full or short commit SHA.
commitMessagestring
Commit message text.
commitAuthorstring
Commit author email or name.
ciProviderstring
CI provider name (e.g., github-actions, gitlab-ci, jenkins).
ciBuildIdstring
CI build or run identifier.
ciBuildUrlstring
URL to the CI build for quick navigation.
playwrightVersionstring
Playwright version used.
workersnumber
Number of parallel workers.
shardCurrentnumber
Current shard index (for distributed testing).
shardTotalnumber
Total number of shards.
browserstring
Browser name (chromium, firefox, webkit).
osstring
Operating system.
viewportstring
Viewport dimensions.
hostnamestring
Machine hostname.
runTitlestring
Custom display title for the run.
tagsstring[]
Array of tags for categorization.
grepPatternsstring[]
Grep filter patterns used.

Responsejson

{
  "id": "run_xyz789",
  "projectId": "proj_abc123",
  "status": "running",
  "branch": "feature/login-flow",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "browser": "chromium",
  "os": "linux",
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

List Test Runs

GET /api/runs

Returns a paginated list of test runs for the authenticated project.

projectIdstringRequired
Filter by project ID (query parameter).
statusstring
Filter by run status (query parameter).
branchstring
Filter by branch name (query parameter).
limitnumber
Number of results per page. Default: 20, max: 100 (query parameter).
offsetnumber
Pagination offset (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/runs?projectId=proj_abc123&status=failed&limit=10" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "run_xyz789",
      "projectId": "proj_abc123",
      "status": "failed",
      "branch": "main",
      "commitSha": "a1b2c3d4e5f6",
      "totalTests": 142,
      "passedTests": 138,
      "failedTests": 3,
      "skippedTests": 0,
      "flakyTests": 1,
      "passRate": 97.18,
      "duration": 245000,
      "createdAt": "2026-03-19T10:00:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Get a Test Run

GET /api/runs/:id

Returns full details for a single test run including all metadata.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/runs/run_xyz789 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "run_xyz789",
  "projectId": "proj_abc123",
  "status": "failed",
  "branch": "main",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "shardCurrent": 1,
  "shardTotal": 3,
  "browser": "chromium",
  "os": "linux",
  "viewport": "1280x720",
  "hostname": "ci-runner-01",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "passRate": 97.18,
  "duration": 245000,
  "runTitle": "Login Flow Tests",
  "tags": ["smoke", "login"],
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:04:05Z"
}

Update a Test Run

PATCH /api/runs/:id

Updates a test run's status and statistics. Typically called when the test suite finishes executing.

Request Bodyjson

{
  "status": "failed",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "duration": 245000
}

statusstring
Updated run status. One of: running, passed, failed, cancelled.
totalTestsnumber
Total number of tests in the run.
passedTestsnumber
Number of passing tests.
failedTestsnumber
Number of failed tests.
skippedTestsnumber
Number of skipped tests.
flakyTestsnumber
Number of flaky tests (passed on retry).
durationnumber
Total run duration in milliseconds.

Responsejson

{
  "id": "run_xyz789",
  "status": "failed",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "duration": 245000,
  "updatedAt": "2026-03-19T10:04:05Z"
}

Delete a Test Run

DELETE /api/runs/:id

Permanently deletes a test run and all associated test results and artifacts.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/runs/run_xyz789 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Run deleted successfully"
}

Deleting a run permanently removes all associated tests, steps, and artifacts. This action cannot be undone.

Tests

Tests represent individual test case results within a run. Each test includes its status, duration, error details, steps, and artifacts.

Create a Test with Result

POST /api/tests

Creates a test result within a run. Includes the test definition, execution result, steps, and error details.

Request Bodyjson

{
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should display login form",
  "fullTitle": "Auth > Login Page > should display login form",
  "filePath": "tests/auth/login.spec.ts",
  "lineNumber": 15,
  "status": "passed",
  "duration": 3420,
  "retries": 0,
  "attempt": 1,
  "isFlaky": false,
  "tags": ["@smoke", "@auth"],
  "annotations": [{ "type": "slow", "description": "Includes network wait" }],
  "error": null,
  "steps": [
    {
      "title": "navigate to /login",
      "category": "action",
      "status": "passed",
      "duration": 820,
      "error": null
    },
    {
      "title": "expect(locator).toBeVisible()",
      "category": "assertion",
      "status": "passed",
      "duration": 45,
      "error": null
    }
  ],
  "stdout": "",
  "stderr": ""
}

runIdstringRequired
The run this test belongs to.
projectIdstringRequired
The project ID.
titlestringRequired
Test title (the it/test block name).
fullTitlestringRequired
Full title path including suite hierarchy.
filePathstring
Relative path to the test file.
lineNumbernumber
Line number in the test file.
statusstringRequired
Test result status. One of: passed, failed, skipped, flaky.
durationnumberRequired
Execution duration in milliseconds.
retriesnumber
Number of retry attempts.
attemptnumber
Current attempt number.
isFlakyboolean
Whether the test was detected as flaky (passed on retry).
tagsstring[]
Test tags from Playwright annotations.
annotationsobject[]
Playwright annotations array with type and description.
errorobject | null
Error details if the test failed. Contains message, stack, expected, and actual.
stepsobject[]
Array of test execution steps. Each step has title, category, status, duration, and optional error.
stdoutstring
Standard output captured during the test.
stderrstring
Standard error output captured during the test.

Responsejson

{
  "id": "test_def456",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should display login form",
  "fullTitle": "Auth > Login Page > should display login form",
  "status": "passed",
  "duration": 3420,
  "isFlaky": false,
  "createdAt": "2026-03-19T10:01:23Z"
}

List Tests

GET /api/tests

Returns a paginated list of tests, optionally filtered by run, status, or search query.

runIdstring
Filter by run ID (query parameter).
projectIdstringRequired
Filter by project ID (query parameter).
statusstring
Filter by test status (query parameter).
searchstring
Search by test title (query parameter).
limitnumber
Results per page. Default: 50, max: 200 (query parameter).
offsetnumber
Pagination offset (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/tests?runId=run_xyz789&status=failed" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "test_def456",
      "runId": "run_xyz789",
      "title": "should submit login form",
      "fullTitle": "Auth > Login Page > should submit login form",
      "filePath": "tests/auth/login.spec.ts",
      "status": "failed",
      "duration": 8320,
      "isFlaky": false,
      "error": {
        "message": "Timed out waiting for selector '.dashboard'",
        "stack": "Error: Timed out...
    at login.spec.ts:42:5"
      },
      "createdAt": "2026-03-19T10:01:30Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Get a Test

GET /api/tests/:id

Returns full details for a single test including error information and metadata.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "test_def456",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should submit login form",
  "fullTitle": "Auth > Login Page > should submit login form",
  "filePath": "tests/auth/login.spec.ts",
  "lineNumber": 35,
  "status": "failed",
  "duration": 8320,
  "retries": 2,
  "attempt": 3,
  "isFlaky": false,
  "tags": ["@smoke", "@auth"],
  "annotations": [],
  "error": {
    "message": "Timed out waiting for selector '.dashboard'",
    "stack": "Error: Timed out waiting for selector '.dashboard'
    at login.spec.ts:42:5",
    "expected": "visible",
    "actual": "hidden"
  },
  "stdout": "",
  "stderr": "",
  "createdAt": "2026-03-19T10:01:30Z"
}

Get Test Steps

GET /api/tests/:id/steps

Returns the execution steps for a test, including actions, assertions, hooks, and fixtures with their individual durations and statuses.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456/steps \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "title": "Before Hooks",
      "category": "hook",
      "status": "passed",
      "duration": 120,
      "error": null
    },
    {
      "title": "page.goto('https://app.example.com/login')",
      "category": "action",
      "status": "passed",
      "duration": 820,
      "error": null
    },
    {
      "title": "locator.fill('#email', 'user@test.com')",
      "category": "action",
      "status": "passed",
      "duration": 45,
      "error": null
    },
    {
      "title": "locator.click('button[type=submit]')",
      "category": "action",
      "status": "passed",
      "duration": 32,
      "error": null
    },
    {
      "title": "expect(locator).toBeVisible()",
      "category": "assertion",
      "status": "failed",
      "duration": 30000,
      "error": {
        "message": "Timed out waiting for selector '.dashboard'"
      }
    },
    {
      "title": "After Hooks",
      "category": "hook",
      "status": "passed",
      "duration": 15,
      "error": null
    }
  ]
}

Step categories include: action, assertion, hook, and fixture. Use these to quickly identify which phase of execution failed.

Get Test History

GET /api/tests/:id/history

Returns the last 20 execution results for a test, showing how it has performed across recent runs. Useful for identifying flakiness patterns and regressions.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456/history \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "runId": "run_xyz789",
      "status": "failed",
      "duration": 8320,
      "branch": "main",
      "createdAt": "2026-03-19T10:01:30Z"
    },
    {
      "runId": "run_xyz788",
      "status": "passed",
      "duration": 3200,
      "branch": "main",
      "createdAt": "2026-03-18T14:22:00Z"
    },
    {
      "runId": "run_xyz787",
      "status": "passed",
      "duration": 3150,
      "branch": "feature/signup",
      "createdAt": "2026-03-18T09:15:00Z"
    }
  ],
  "total": 20
}

Test Suites

Test suites organize tests by file and describe block hierarchy. They are automatically created when tests are reported.

Create a Test Suite

POST /api/test-suites

Creates or upserts a test suite. If a suite with the same title and file path already exists, it is updated rather than duplicated.

Request Bodyjson

{
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "Login Page",
  "filePath": "tests/auth/login.spec.ts",
  "parentSuiteId": "suite_parent123"
}

runIdstringRequired
The run this suite belongs to.
projectIdstringRequired
The project ID.
titlestringRequired
Suite title (describe block name).
filePathstring
Path to the test file containing this suite.
parentSuiteIdstring
Parent suite ID for nested suites.

Responsejson

{
  "id": "suite_abc123",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "Login Page",
  "filePath": "tests/auth/login.spec.ts",
  "parentSuiteId": "suite_parent123",
  "createdAt": "2026-03-19T10:00:05Z"
}

List Test Suites

GET /api/test-suites

Returns test suites with their hierarchy for a given run.

runIdstringRequired
Filter by run ID (query parameter).
projectIdstringRequired
Filter by project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/test-suites?runId=run_xyz789&projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "suite_root1",
      "title": "Auth",
      "filePath": "tests/auth/login.spec.ts",
      "parentSuiteId": null,
      "children": [
        {
          "id": "suite_abc123",
          "title": "Login Page",
          "filePath": "tests/auth/login.spec.ts",
          "parentSuiteId": "suite_root1",
          "children": []
        }
      ]
    }
  ]
}

Flakiness

Retrieve flakiness scores for tests and manage quarantine status. Flakiness scores range from 0 (stable) to 1 (highly flaky) and are calculated across historical runs.

Get Flakiness Data

GET /api/flakiness

Returns flakiness data for all tests in a project, sorted by flakiness score (highest first).

projectIdstringRequired
Project ID (query parameter).
minScorenumber
Minimum flakiness score to include. Default: 0 (query parameter).
quarantinedboolean
Filter by quarantine status (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/flakiness?projectId=proj_abc123&minScore=0.3" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "testId": "test_def456",
      "testTitle": "should submit login form",
      "filePath": "tests/auth/login.spec.ts",
      "flakinessScore": 0.72,
      "totalRuns": 45,
      "flakyRuns": 18,
      "lastFlakyAt": "2026-03-19T08:30:00Z",
      "isQuarantined": true
    },
    {
      "testId": "test_ghi789",
      "testTitle": "should load dashboard widgets",
      "filePath": "tests/dashboard/widgets.spec.ts",
      "flakinessScore": 0.35,
      "totalRuns": 60,
      "flakyRuns": 12,
      "lastFlakyAt": "2026-03-18T16:45:00Z",
      "isQuarantined": false
    }
  ],
  "summary": {
    "totalFlakyTests": 8,
    "quarantinedTests": 3,
    "averageFlakinessScore": 0.28
  }
}

Update Quarantine Status

POST /api/flakiness

Manually quarantine or unquarantine a test. Quarantined tests are flagged in the dashboard so the team knows they are being managed.

Request Bodyjson

{
  "testId": "test_def456",
  "projectId": "proj_abc123",
  "isQuarantined": true
}

testIdstringRequired
The test to quarantine or unquarantine.
projectIdstringRequired
The project ID.
isQuarantinedbooleanRequired
Set to true to quarantine, false to unquarantine.

Responsejson

{
  "testId": "test_def456",
  "isQuarantined": true,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Auto-quarantine can be enabled in project settings. When enabled, tests exceeding the configured flakiness threshold are automatically quarantined.

File Upload

Upload test artifacts such as screenshots, videos, Playwright traces, and HTML reports. Files are stored securely and served via time-limited signed URLs.

Upload Artifact

POST /api/upload

Uploads a file artifact using multipart form-data. Returns a signed URL for accessing the uploaded file.

Example Requestbash

curl -X POST https://app.euriqa.dev/api/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@screenshot.png" \
  -F "type=screenshot" \
  -F "runId=run_xyz789" \
  -F "testId=test_def456" \
  -F "projectId=proj_abc123"

fileFileRequired
The file to upload (multipart form field).
typestringRequired
Artifact type. One of: screenshot, video, trace, report.
runIdstringRequired
The run this artifact belongs to.
testIdstring
The test this artifact belongs to (optional for reports).
projectIdstringRequired
The project ID.

Responsejson

{
  "id": "artifact_uvw123",
  "type": "screenshot",
  "fileName": "screenshot.png",
  "fileSize": 245678,
  "mimeType": "image/png",
  "url": "https://storage.euriqa.dev/artifacts/proj_abc123/run_xyz789/screenshot.png?token=signed-token",
  "expiresAt": "2026-03-19T11:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Accepted MIME Types

Type	Formats	Max Size
screenshot	PNG, JPG, JPEG, WebP, GIF	5 MB
video	WebM, MP4, AVI, MOV	100 MB
trace	ZIP	50 MB
report	ZIP	200 MB

Files exceeding the size limit are rejected with a 413 status code. Size limits are configurable in the SDK via the fileSizeLimits option. Signed URLs expire after 1 hour by default.

Projects

Projects are the primary organizational unit in Euriqa. Each project has its own test data, API keys, settings, and webhooks, isolated from other projects.

List Projects

GET /api/projects

Returns all projects for the authenticated user's team.

teamIdstringRequired
Filter by team ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/projects?teamId=team_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Web App E2E",
      "teamId": "team_abc123",
      "createdAt": "2026-01-15T08:00:00Z",
      "updatedAt": "2026-03-19T10:00:00Z"
    },
    {
      "id": "proj_def456",
      "name": "API Integration Tests",
      "teamId": "team_abc123",
      "createdAt": "2026-02-01T12:00:00Z",
      "updatedAt": "2026-03-18T15:30:00Z"
    }
  ]
}

Create a Project

POST /api/projects

Creates a new project within a team.

Request Bodyjson

{
  "name": "Mobile App E2E",
  "teamId": "team_abc123"
}

namestringRequired
Project name.
teamIdstringRequired
Team the project belongs to.

Responsejson

{
  "id": "proj_ghi789",
  "name": "Mobile App E2E",
  "teamId": "team_abc123",
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Get a Project

GET /api/projects/:id

Returns details for a single project.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/projects/proj_abc123 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "proj_abc123",
  "name": "Web App E2E",
  "teamId": "team_abc123",
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Update a Project

PATCH /api/projects/:id

Updates a project's name or settings.

Request Bodyjson

{
  "name": "Web App E2E (Production)"
}

namestring
Updated project name.

Responsejson

{
  "id": "proj_abc123",
  "name": "Web App E2E (Production)",
  "teamId": "team_abc123",
  "updatedAt": "2026-03-19T10:05:00Z"
}

Delete a Project

DELETE /api/projects/:id

Permanently deletes a project and all its associated data including runs, tests, artifacts, API keys, and webhooks.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/projects/proj_abc123 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Project deleted successfully"
}

Deleting a project permanently removes all runs, tests, artifacts, API keys, and webhooks. This action cannot be undone. Only team Owners and Admins can delete projects.

Teams

Teams are the top-level organizational unit. Each team has its own members, projects, and access controls.

List Teams

GET /api/teams

Returns all teams the authenticated user belongs to.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/teams \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "team_abc123",
      "name": "Acme Engineering",
      "createdAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "team_def456",
      "name": "Platform Team",
      "createdAt": "2026-02-15T12:00:00Z"
    }
  ]
}

Create a Team

POST /api/teams

Creates a new team. The authenticated user becomes the team Owner.

Request Bodyjson

{
  "name": "QA Automation Team"
}

namestringRequired
Team name.

Responsejson

{
  "id": "team_ghi789",
  "name": "QA Automation Team",
  "createdAt": "2026-03-19T10:00:00Z"
}

Team Members

Manage team membership and roles. Euriqa supports four roles: Owner, Admin, Member, and Viewer.

List Team Members

GET /api/team-members

Returns all members of a team with their roles.

teamIdstringRequired
Team ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/team-members?teamId=team_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "member_001",
      "userId": "user_abc",
      "teamId": "team_abc123",
      "role": "owner",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "avatarUrl": "https://example.com/avatars/jane.jpg",
      "joinedAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "member_002",
      "userId": "user_def",
      "teamId": "team_abc123",
      "role": "member",
      "name": "John Doe",
      "email": "john@example.com",
      "avatarUrl": null,
      "joinedAt": "2026-01-12T14:30:00Z"
    }
  ]
}

Add a Team Member

POST /api/team-members

Sends an invitation to add a new member to the team. The invitation is sent via email and expires after 7 days.

Request Bodyjson

{
  "teamId": "team_abc123",
  "email": "newmember@example.com",
  "role": "member"
}

teamIdstringRequired
Team to add the member to.
emailstringRequired
Email address of the user to invite.
rolestringRequired
Role to assign. One of: admin, member, viewer.

Responsejson

{
  "id": "invite_xyz789",
  "teamId": "team_abc123",
  "email": "newmember@example.com",
  "role": "member",
  "status": "pending",
  "expiresAt": "2026-03-26T10:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Only team Owners and Admins can add new members. Invitations expire after 7 days if not accepted.

API Keys

API keys are scoped to a specific project and used for CI/CD authentication. Each key can be named, tracked, and activated or deactivated without deletion.

List API Keys

GET /api/api-keys

Returns all API keys for a project. Key values are masked for security.

projectIdstringRequired
Project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/api-keys?projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "key_abc123",
      "name": "GitHub Actions",
      "projectId": "proj_abc123",
      "maskedKey": "eur_****...****a1b2",
      "isActive": true,
      "expiresAt": null,
      "lastUsedAt": "2026-03-19T09:45:00Z",
      "createdAt": "2026-01-15T08:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "Local Dev",
      "projectId": "proj_abc123",
      "maskedKey": "eur_****...****c3d4",
      "isActive": false,
      "expiresAt": "2026-06-01T00:00:00Z",
      "lastUsedAt": "2026-03-10T16:20:00Z",
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ]
}

Create an API Key

POST /api/api-keys

Generates a new API key for a project. The full key value is only returned once at creation time.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "name": "GitLab CI",
  "expiresAt": "2026-12-31T23:59:59Z"
}

projectIdstringRequired
Project the key is scoped to.
namestringRequired
Descriptive name for the key.
expiresAtstring
Optional ISO 8601 expiration date.

Responsejson

{
  "id": "key_ghi789",
  "name": "GitLab CI",
  "projectId": "proj_abc123",
  "key": "eur_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": true,
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Store the API key securely. The full key value is only shown once. After creation, only the masked version is available.

Deactivate an API Key

PATCH /api/api-keys/:id

Deactivates or reactivates an API key. Deactivated keys are rejected on all API calls.

Request Bodyjson

{
  "isActive": false
}

isActivebooleanRequired
Set to false to deactivate, true to reactivate.

Responsejson

{
  "id": "key_abc123",
  "name": "GitHub Actions",
  "isActive": false,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Webhooks

Webhooks notify external services when events happen in your project. Use them to trigger Slack notifications, PagerDuty alerts, deployment pipelines, or custom integrations.

List Webhooks

GET /api/webhooks

Returns all webhooks configured for a project.

projectIdstringRequired
Project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/webhooks?projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "wh_abc123",
      "projectId": "proj_abc123",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "events": ["run.completed", "run.failed"],
      "headers": { "X-Custom-Header": "value" },
      "isActive": true,
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ]
}

Create a Webhook

POST /api/webhooks

Creates a new webhook for a project.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["run.completed", "run.failed"],
  "headers": { "X-Custom-Header": "value" },
  "secret": "whsec_your-webhook-secret"
}

projectIdstringRequired
Project this webhook belongs to.
urlstringRequired
The URL to send webhook payloads to.
eventsstring[]Required
Events to subscribe to. Options: run.completed, run.failed.
headersobject
Custom headers to include in webhook requests.
secretstring
Webhook secret for request signature verification.

Responsejson

{
  "id": "wh_def456",
  "projectId": "proj_abc123",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["run.completed", "run.failed"],
  "isActive": true,
  "createdAt": "2026-03-19T10:00:00Z"
}

Update a Webhook

PATCH /api/webhooks/:id

Updates a webhook's URL, events, headers, secret, or active status.

Request Bodyjson

{
  "url": "https://hooks.slack.com/services/T00/B00/new-url",
  "events": ["run.failed"],
  "isActive": true
}

urlstring
Updated webhook URL.
eventsstring[]
Updated event subscriptions.
headersobject
Updated custom headers.
secretstring
Updated webhook secret.
isActiveboolean
Set to false to deactivate without deleting.

Responsejson

{
  "id": "wh_def456",
  "url": "https://hooks.slack.com/services/T00/B00/new-url",
  "events": ["run.failed"],
  "isActive": true,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Delete a Webhook

DELETE /api/webhooks/:id

Permanently deletes a webhook.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/webhooks/wh_def456 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Project Settings

Configure per-project settings including data retention, flakiness thresholds, and auto-quarantine behavior.

Get Project Settings

GET /api/projects/:id/settings

Returns the current settings for a project.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/projects/proj_abc123/settings \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "projectId": "proj_abc123",
  "dataRetentionDays": 90,
  "flakinessThreshold": 0.3,
  "autoQuarantineEnabled": true,
  "updatedAt": "2026-03-15T08:00:00Z"
}

Update Project Settings

PATCH /api/projects/:id/settings

Updates project settings. Only the provided fields are updated.

Request Bodyjson

{
  "dataRetentionDays": 180,
  "flakinessThreshold": 0.5,
  "autoQuarantineEnabled": false
}

dataRetentionDaysnumber
Number of days to retain test data. Default: 90.
flakinessThresholdnumber
Flakiness score threshold for flagging tests (0 to 1). Default: 0.3.
autoQuarantineEnabledboolean
Whether to automatically quarantine tests exceeding the flakiness threshold.

Responsejson

{
  "projectId": "proj_abc123",
  "dataRetentionDays": 180,
  "flakinessThreshold": 0.5,
  "autoQuarantineEnabled": false,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Error Responses

All error responses follow a consistent JSON format with an error code and human-readable message.

Error Formatjson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'projectId' is required",
    "details": {
      "field": "projectId",
      "reason": "required"
    }
  }
}

Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded.
`201`	Created	Resource created successfully.
`400`	Bad Request	Invalid request body or parameters. Check the error message for details.
`401`	Unauthorized	Missing or invalid authentication. Verify your API key or session token.
`403`	Forbidden	Authenticated but insufficient permissions for the requested action.
`404`	Not Found	The requested resource does not exist.
`413`	Payload Too Large	Uploaded file exceeds the size limit for its artifact type.
`429`	Too Many Requests	Rate limit exceeded. Retry after the delay specified in the Retry-After header.
`500`	Internal Server Error	Unexpected server error. Contact support if the issue persists.

Rate Limits

API requests are rate-limited per API key to ensure platform stability. When a rate limit is exceeded, requests return a 429 status with a Retry-After header indicating when to retry.

Endpoint Group	Rate Limit	Window
Test Runs (read)	100 requests	Per minute
Test Runs (write)	30 requests	Per minute
Tests (read)	200 requests	Per minute
Tests (write)	60 requests	Per minute
File Uploads	30 requests	Per minute
Projects / Teams	60 requests	Per minute
API Keys / Webhooks	30 requests	Per minute
Flakiness	60 requests	Per minute

Rate limits are applied per API key. If you need higher limits, contact us at support@euriqa.dev.

API Reference

Complete reference for the Euriqa REST API. Use the API to programmatically manage test runs, results, artifacts, projects, teams, and more.

Base URL

All API requests are made to the following base URL:

bash

https://app.euriqa.dev/api

All API communication requires HTTPS. HTTP requests will be rejected.

Authentication

Euriqa supports two authentication methods. Both enforce the same authorization rules.

API Key

Use an API key for CI/CD pipelines and programmatic access. Pass your key via the X-API-Key header.

API Key Authenticationbash

curl -X GET https://app.euriqa.dev/api/runs \
  -H "X-API-Key: your-api-key"

Session Cookie

Browser-based authentication uses a session cookie set during login. This is used automatically by the Euriqa dashboard.

Session Cookie Authenticationbash

curl -X GET https://app.euriqa.dev/api/runs \
  -H "Cookie: sb-access-token=your-session-token"

API keys are scoped to a specific project. Generate them from the project settings page in the dashboard.

Test Runs

Test runs represent a single execution of your test suite. Each run contains metadata about the CI environment, branch, commit, and aggregate test results.

Create a Test Run

POST /api/runs

Creates a new test run. Typically called at the start of a test suite execution.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "status": "running",
  "branch": "feature/login-flow",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "shardCurrent": 1,
  "shardTotal": 3,
  "browser": "chromium",
  "os": "linux",
  "viewport": "1280x720",
  "hostname": "ci-runner-01",
  "runTitle": "Login Flow Tests",
  "tags": ["smoke", "login"],
  "grepPatterns": ["@smoke"]
}

projectIdstringRequired
The project ID this run belongs to.
statusstringRequired
Initial run status. One of: running, passed, failed.
branchstring
Git branch name.
commitShastring
Full or short commit SHA.
commitMessagestring
Commit message text.
commitAuthorstring
Commit author email or name.
ciProviderstring
CI provider name (e.g., github-actions, gitlab-ci, jenkins).
ciBuildIdstring
CI build or run identifier.
ciBuildUrlstring
URL to the CI build for quick navigation.
playwrightVersionstring
Playwright version used.
workersnumber
Number of parallel workers.
shardCurrentnumber
Current shard index (for distributed testing).
shardTotalnumber
Total number of shards.
browserstring
Browser name (chromium, firefox, webkit).
osstring
Operating system.
viewportstring
Viewport dimensions.
hostnamestring
Machine hostname.
runTitlestring
Custom display title for the run.
tagsstring[]
Array of tags for categorization.
grepPatternsstring[]
Grep filter patterns used.

Responsejson

{
  "id": "run_xyz789",
  "projectId": "proj_abc123",
  "status": "running",
  "branch": "feature/login-flow",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "browser": "chromium",
  "os": "linux",
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

List Test Runs

GET /api/runs

Returns a paginated list of test runs for the authenticated project.

projectIdstringRequired
Filter by project ID (query parameter).
statusstring
Filter by run status (query parameter).
branchstring
Filter by branch name (query parameter).
limitnumber
Number of results per page. Default: 20, max: 100 (query parameter).
offsetnumber
Pagination offset (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/runs?projectId=proj_abc123&status=failed&limit=10" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "run_xyz789",
      "projectId": "proj_abc123",
      "status": "failed",
      "branch": "main",
      "commitSha": "a1b2c3d4e5f6",
      "totalTests": 142,
      "passedTests": 138,
      "failedTests": 3,
      "skippedTests": 0,
      "flakyTests": 1,
      "passRate": 97.18,
      "duration": 245000,
      "createdAt": "2026-03-19T10:00:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Get a Test Run

GET /api/runs/:id

Returns full details for a single test run including all metadata.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/runs/run_xyz789 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "run_xyz789",
  "projectId": "proj_abc123",
  "status": "failed",
  "branch": "main",
  "commitSha": "a1b2c3d4e5f6",
  "commitMessage": "Add login flow tests",
  "commitAuthor": "jane@example.com",
  "ciProvider": "github-actions",
  "ciBuildId": "run-12345",
  "ciBuildUrl": "https://github.com/org/repo/actions/runs/12345",
  "playwrightVersion": "1.52.0",
  "workers": 4,
  "shardCurrent": 1,
  "shardTotal": 3,
  "browser": "chromium",
  "os": "linux",
  "viewport": "1280x720",
  "hostname": "ci-runner-01",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "passRate": 97.18,
  "duration": 245000,
  "runTitle": "Login Flow Tests",
  "tags": ["smoke", "login"],
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:04:05Z"
}

Update a Test Run

PATCH /api/runs/:id

Updates a test run's status and statistics. Typically called when the test suite finishes executing.

Request Bodyjson

{
  "status": "failed",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "duration": 245000
}

statusstring
Updated run status. One of: running, passed, failed, cancelled.
totalTestsnumber
Total number of tests in the run.
passedTestsnumber
Number of passing tests.
failedTestsnumber
Number of failed tests.
skippedTestsnumber
Number of skipped tests.
flakyTestsnumber
Number of flaky tests (passed on retry).
durationnumber
Total run duration in milliseconds.

Responsejson

{
  "id": "run_xyz789",
  "status": "failed",
  "totalTests": 142,
  "passedTests": 138,
  "failedTests": 3,
  "skippedTests": 0,
  "flakyTests": 1,
  "duration": 245000,
  "updatedAt": "2026-03-19T10:04:05Z"
}

Delete a Test Run

DELETE /api/runs/:id

Permanently deletes a test run and all associated test results and artifacts.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/runs/run_xyz789 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Run deleted successfully"
}

Deleting a run permanently removes all associated tests, steps, and artifacts. This action cannot be undone.

Tests

Tests represent individual test case results within a run. Each test includes its status, duration, error details, steps, and artifacts.

Create a Test with Result

POST /api/tests

Creates a test result within a run. Includes the test definition, execution result, steps, and error details.

Request Bodyjson

{
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should display login form",
  "fullTitle": "Auth > Login Page > should display login form",
  "filePath": "tests/auth/login.spec.ts",
  "lineNumber": 15,
  "status": "passed",
  "duration": 3420,
  "retries": 0,
  "attempt": 1,
  "isFlaky": false,
  "tags": ["@smoke", "@auth"],
  "annotations": [{ "type": "slow", "description": "Includes network wait" }],
  "error": null,
  "steps": [
    {
      "title": "navigate to /login",
      "category": "action",
      "status": "passed",
      "duration": 820,
      "error": null
    },
    {
      "title": "expect(locator).toBeVisible()",
      "category": "assertion",
      "status": "passed",
      "duration": 45,
      "error": null
    }
  ],
  "stdout": "",
  "stderr": ""
}

runIdstringRequired
The run this test belongs to.
projectIdstringRequired
The project ID.
titlestringRequired
Test title (the it/test block name).
fullTitlestringRequired
Full title path including suite hierarchy.
filePathstring
Relative path to the test file.
lineNumbernumber
Line number in the test file.
statusstringRequired
Test result status. One of: passed, failed, skipped, flaky.
durationnumberRequired
Execution duration in milliseconds.
retriesnumber
Number of retry attempts.
attemptnumber
Current attempt number.
isFlakyboolean
Whether the test was detected as flaky (passed on retry).
tagsstring[]
Test tags from Playwright annotations.
annotationsobject[]
Playwright annotations array with type and description.
errorobject | null
Error details if the test failed. Contains message, stack, expected, and actual.
stepsobject[]
Array of test execution steps. Each step has title, category, status, duration, and optional error.
stdoutstring
Standard output captured during the test.
stderrstring
Standard error output captured during the test.

Responsejson

{
  "id": "test_def456",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should display login form",
  "fullTitle": "Auth > Login Page > should display login form",
  "status": "passed",
  "duration": 3420,
  "isFlaky": false,
  "createdAt": "2026-03-19T10:01:23Z"
}

List Tests

GET /api/tests

Returns a paginated list of tests, optionally filtered by run, status, or search query.

runIdstring
Filter by run ID (query parameter).
projectIdstringRequired
Filter by project ID (query parameter).
statusstring
Filter by test status (query parameter).
searchstring
Search by test title (query parameter).
limitnumber
Results per page. Default: 50, max: 200 (query parameter).
offsetnumber
Pagination offset (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/tests?runId=run_xyz789&status=failed" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "test_def456",
      "runId": "run_xyz789",
      "title": "should submit login form",
      "fullTitle": "Auth > Login Page > should submit login form",
      "filePath": "tests/auth/login.spec.ts",
      "status": "failed",
      "duration": 8320,
      "isFlaky": false,
      "error": {
        "message": "Timed out waiting for selector '.dashboard'",
        "stack": "Error: Timed out...
    at login.spec.ts:42:5"
      },
      "createdAt": "2026-03-19T10:01:30Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Get a Test

GET /api/tests/:id

Returns full details for a single test including error information and metadata.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "test_def456",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "should submit login form",
  "fullTitle": "Auth > Login Page > should submit login form",
  "filePath": "tests/auth/login.spec.ts",
  "lineNumber": 35,
  "status": "failed",
  "duration": 8320,
  "retries": 2,
  "attempt": 3,
  "isFlaky": false,
  "tags": ["@smoke", "@auth"],
  "annotations": [],
  "error": {
    "message": "Timed out waiting for selector '.dashboard'",
    "stack": "Error: Timed out waiting for selector '.dashboard'
    at login.spec.ts:42:5",
    "expected": "visible",
    "actual": "hidden"
  },
  "stdout": "",
  "stderr": "",
  "createdAt": "2026-03-19T10:01:30Z"
}

Get Test Steps

GET /api/tests/:id/steps

Returns the execution steps for a test, including actions, assertions, hooks, and fixtures with their individual durations and statuses.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456/steps \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "title": "Before Hooks",
      "category": "hook",
      "status": "passed",
      "duration": 120,
      "error": null
    },
    {
      "title": "page.goto('https://app.example.com/login')",
      "category": "action",
      "status": "passed",
      "duration": 820,
      "error": null
    },
    {
      "title": "locator.fill('#email', 'user@test.com')",
      "category": "action",
      "status": "passed",
      "duration": 45,
      "error": null
    },
    {
      "title": "locator.click('button[type=submit]')",
      "category": "action",
      "status": "passed",
      "duration": 32,
      "error": null
    },
    {
      "title": "expect(locator).toBeVisible()",
      "category": "assertion",
      "status": "failed",
      "duration": 30000,
      "error": {
        "message": "Timed out waiting for selector '.dashboard'"
      }
    },
    {
      "title": "After Hooks",
      "category": "hook",
      "status": "passed",
      "duration": 15,
      "error": null
    }
  ]
}

Step categories include: action, assertion, hook, and fixture. Use these to quickly identify which phase of execution failed.

Get Test History

GET /api/tests/:id/history

Returns the last 20 execution results for a test, showing how it has performed across recent runs. Useful for identifying flakiness patterns and regressions.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/tests/test_def456/history \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "runId": "run_xyz789",
      "status": "failed",
      "duration": 8320,
      "branch": "main",
      "createdAt": "2026-03-19T10:01:30Z"
    },
    {
      "runId": "run_xyz788",
      "status": "passed",
      "duration": 3200,
      "branch": "main",
      "createdAt": "2026-03-18T14:22:00Z"
    },
    {
      "runId": "run_xyz787",
      "status": "passed",
      "duration": 3150,
      "branch": "feature/signup",
      "createdAt": "2026-03-18T09:15:00Z"
    }
  ],
  "total": 20
}

Test Suites

Test suites organize tests by file and describe block hierarchy. They are automatically created when tests are reported.

Create a Test Suite

POST /api/test-suites

Creates or upserts a test suite. If a suite with the same title and file path already exists, it is updated rather than duplicated.

Request Bodyjson

{
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "Login Page",
  "filePath": "tests/auth/login.spec.ts",
  "parentSuiteId": "suite_parent123"
}

runIdstringRequired
The run this suite belongs to.
projectIdstringRequired
The project ID.
titlestringRequired
Suite title (describe block name).
filePathstring
Path to the test file containing this suite.
parentSuiteIdstring
Parent suite ID for nested suites.

Responsejson

{
  "id": "suite_abc123",
  "runId": "run_xyz789",
  "projectId": "proj_abc123",
  "title": "Login Page",
  "filePath": "tests/auth/login.spec.ts",
  "parentSuiteId": "suite_parent123",
  "createdAt": "2026-03-19T10:00:05Z"
}

List Test Suites

GET /api/test-suites

Returns test suites with their hierarchy for a given run.

runIdstringRequired
Filter by run ID (query parameter).
projectIdstringRequired
Filter by project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/test-suites?runId=run_xyz789&projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "suite_root1",
      "title": "Auth",
      "filePath": "tests/auth/login.spec.ts",
      "parentSuiteId": null,
      "children": [
        {
          "id": "suite_abc123",
          "title": "Login Page",
          "filePath": "tests/auth/login.spec.ts",
          "parentSuiteId": "suite_root1",
          "children": []
        }
      ]
    }
  ]
}

Flakiness

Retrieve flakiness scores for tests and manage quarantine status. Flakiness scores range from 0 (stable) to 1 (highly flaky) and are calculated across historical runs.

Get Flakiness Data

GET /api/flakiness

Returns flakiness data for all tests in a project, sorted by flakiness score (highest first).

projectIdstringRequired
Project ID (query parameter).
minScorenumber
Minimum flakiness score to include. Default: 0 (query parameter).
quarantinedboolean
Filter by quarantine status (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/flakiness?projectId=proj_abc123&minScore=0.3" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "testId": "test_def456",
      "testTitle": "should submit login form",
      "filePath": "tests/auth/login.spec.ts",
      "flakinessScore": 0.72,
      "totalRuns": 45,
      "flakyRuns": 18,
      "lastFlakyAt": "2026-03-19T08:30:00Z",
      "isQuarantined": true
    },
    {
      "testId": "test_ghi789",
      "testTitle": "should load dashboard widgets",
      "filePath": "tests/dashboard/widgets.spec.ts",
      "flakinessScore": 0.35,
      "totalRuns": 60,
      "flakyRuns": 12,
      "lastFlakyAt": "2026-03-18T16:45:00Z",
      "isQuarantined": false
    }
  ],
  "summary": {
    "totalFlakyTests": 8,
    "quarantinedTests": 3,
    "averageFlakinessScore": 0.28
  }
}

Update Quarantine Status

POST /api/flakiness

Manually quarantine or unquarantine a test. Quarantined tests are flagged in the dashboard so the team knows they are being managed.

Request Bodyjson

{
  "testId": "test_def456",
  "projectId": "proj_abc123",
  "isQuarantined": true
}

testIdstringRequired
The test to quarantine or unquarantine.
projectIdstringRequired
The project ID.
isQuarantinedbooleanRequired
Set to true to quarantine, false to unquarantine.

Responsejson

{
  "testId": "test_def456",
  "isQuarantined": true,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Auto-quarantine can be enabled in project settings. When enabled, tests exceeding the configured flakiness threshold are automatically quarantined.

File Upload

Upload test artifacts such as screenshots, videos, Playwright traces, and HTML reports. Files are stored securely and served via time-limited signed URLs.

Upload Artifact

POST /api/upload

Uploads a file artifact using multipart form-data. Returns a signed URL for accessing the uploaded file.

Example Requestbash

curl -X POST https://app.euriqa.dev/api/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@screenshot.png" \
  -F "type=screenshot" \
  -F "runId=run_xyz789" \
  -F "testId=test_def456" \
  -F "projectId=proj_abc123"

fileFileRequired
The file to upload (multipart form field).
typestringRequired
Artifact type. One of: screenshot, video, trace, report.
runIdstringRequired
The run this artifact belongs to.
testIdstring
The test this artifact belongs to (optional for reports).
projectIdstringRequired
The project ID.

Responsejson

{
  "id": "artifact_uvw123",
  "type": "screenshot",
  "fileName": "screenshot.png",
  "fileSize": 245678,
  "mimeType": "image/png",
  "url": "https://storage.euriqa.dev/artifacts/proj_abc123/run_xyz789/screenshot.png?token=signed-token",
  "expiresAt": "2026-03-19T11:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Accepted MIME Types

Type	Formats	Max Size
screenshot	PNG, JPG, JPEG, WebP, GIF	5 MB
video	WebM, MP4, AVI, MOV	100 MB
trace	ZIP	50 MB
report	ZIP	200 MB

Files exceeding the size limit are rejected with a 413 status code. Size limits are configurable in the SDK via the fileSizeLimits option. Signed URLs expire after 1 hour by default.

Projects

Projects are the primary organizational unit in Euriqa. Each project has its own test data, API keys, settings, and webhooks, isolated from other projects.

List Projects

GET /api/projects

Returns all projects for the authenticated user's team.

teamIdstringRequired
Filter by team ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/projects?teamId=team_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Web App E2E",
      "teamId": "team_abc123",
      "createdAt": "2026-01-15T08:00:00Z",
      "updatedAt": "2026-03-19T10:00:00Z"
    },
    {
      "id": "proj_def456",
      "name": "API Integration Tests",
      "teamId": "team_abc123",
      "createdAt": "2026-02-01T12:00:00Z",
      "updatedAt": "2026-03-18T15:30:00Z"
    }
  ]
}

Create a Project

POST /api/projects

Creates a new project within a team.

Request Bodyjson

{
  "name": "Mobile App E2E",
  "teamId": "team_abc123"
}

namestringRequired
Project name.
teamIdstringRequired
Team the project belongs to.

Responsejson

{
  "id": "proj_ghi789",
  "name": "Mobile App E2E",
  "teamId": "team_abc123",
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Get a Project

GET /api/projects/:id

Returns details for a single project.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/projects/proj_abc123 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "id": "proj_abc123",
  "name": "Web App E2E",
  "teamId": "team_abc123",
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Update a Project

PATCH /api/projects/:id

Updates a project's name or settings.

Request Bodyjson

{
  "name": "Web App E2E (Production)"
}

namestring
Updated project name.

Responsejson

{
  "id": "proj_abc123",
  "name": "Web App E2E (Production)",
  "teamId": "team_abc123",
  "updatedAt": "2026-03-19T10:05:00Z"
}

Delete a Project

DELETE /api/projects/:id

Permanently deletes a project and all its associated data including runs, tests, artifacts, API keys, and webhooks.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/projects/proj_abc123 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Project deleted successfully"
}

Deleting a project permanently removes all runs, tests, artifacts, API keys, and webhooks. This action cannot be undone. Only team Owners and Admins can delete projects.

Teams

Teams are the top-level organizational unit. Each team has its own members, projects, and access controls.

List Teams

GET /api/teams

Returns all teams the authenticated user belongs to.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/teams \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "team_abc123",
      "name": "Acme Engineering",
      "createdAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "team_def456",
      "name": "Platform Team",
      "createdAt": "2026-02-15T12:00:00Z"
    }
  ]
}

Create a Team

POST /api/teams

Creates a new team. The authenticated user becomes the team Owner.

Request Bodyjson

{
  "name": "QA Automation Team"
}

namestringRequired
Team name.

Responsejson

{
  "id": "team_ghi789",
  "name": "QA Automation Team",
  "createdAt": "2026-03-19T10:00:00Z"
}

Team Members

Manage team membership and roles. Euriqa supports four roles: Owner, Admin, Member, and Viewer.

List Team Members

GET /api/team-members

Returns all members of a team with their roles.

teamIdstringRequired
Team ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/team-members?teamId=team_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "member_001",
      "userId": "user_abc",
      "teamId": "team_abc123",
      "role": "owner",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "avatarUrl": "https://example.com/avatars/jane.jpg",
      "joinedAt": "2026-01-10T08:00:00Z"
    },
    {
      "id": "member_002",
      "userId": "user_def",
      "teamId": "team_abc123",
      "role": "member",
      "name": "John Doe",
      "email": "john@example.com",
      "avatarUrl": null,
      "joinedAt": "2026-01-12T14:30:00Z"
    }
  ]
}

Add a Team Member

POST /api/team-members

Sends an invitation to add a new member to the team. The invitation is sent via email and expires after 7 days.

Request Bodyjson

{
  "teamId": "team_abc123",
  "email": "newmember@example.com",
  "role": "member"
}

teamIdstringRequired
Team to add the member to.
emailstringRequired
Email address of the user to invite.
rolestringRequired
Role to assign. One of: admin, member, viewer.

Responsejson

{
  "id": "invite_xyz789",
  "teamId": "team_abc123",
  "email": "newmember@example.com",
  "role": "member",
  "status": "pending",
  "expiresAt": "2026-03-26T10:00:00Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Only team Owners and Admins can add new members. Invitations expire after 7 days if not accepted.

API Keys

API keys are scoped to a specific project and used for CI/CD authentication. Each key can be named, tracked, and activated or deactivated without deletion.

List API Keys

GET /api/api-keys

Returns all API keys for a project. Key values are masked for security.

projectIdstringRequired
Project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/api-keys?projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "key_abc123",
      "name": "GitHub Actions",
      "projectId": "proj_abc123",
      "maskedKey": "eur_****...****a1b2",
      "isActive": true,
      "expiresAt": null,
      "lastUsedAt": "2026-03-19T09:45:00Z",
      "createdAt": "2026-01-15T08:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "Local Dev",
      "projectId": "proj_abc123",
      "maskedKey": "eur_****...****c3d4",
      "isActive": false,
      "expiresAt": "2026-06-01T00:00:00Z",
      "lastUsedAt": "2026-03-10T16:20:00Z",
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ]
}

Create an API Key

POST /api/api-keys

Generates a new API key for a project. The full key value is only returned once at creation time.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "name": "GitLab CI",
  "expiresAt": "2026-12-31T23:59:59Z"
}

projectIdstringRequired
Project the key is scoped to.
namestringRequired
Descriptive name for the key.
expiresAtstring
Optional ISO 8601 expiration date.

Responsejson

{
  "id": "key_ghi789",
  "name": "GitLab CI",
  "projectId": "proj_abc123",
  "key": "eur_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "isActive": true,
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-03-19T10:00:00Z"
}

Store the API key securely. The full key value is only shown once. After creation, only the masked version is available.

Deactivate an API Key

PATCH /api/api-keys/:id

Deactivates or reactivates an API key. Deactivated keys are rejected on all API calls.

Request Bodyjson

{
  "isActive": false
}

isActivebooleanRequired
Set to false to deactivate, true to reactivate.

Responsejson

{
  "id": "key_abc123",
  "name": "GitHub Actions",
  "isActive": false,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Webhooks

Webhooks notify external services when events happen in your project. Use them to trigger Slack notifications, PagerDuty alerts, deployment pipelines, or custom integrations.

List Webhooks

GET /api/webhooks

Returns all webhooks configured for a project.

projectIdstringRequired
Project ID (query parameter).

Example Requestbash

curl -X GET "https://app.euriqa.dev/api/webhooks?projectId=proj_abc123" \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "data": [
    {
      "id": "wh_abc123",
      "projectId": "proj_abc123",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "events": ["run.completed", "run.failed"],
      "headers": { "X-Custom-Header": "value" },
      "isActive": true,
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ]
}

Create a Webhook

POST /api/webhooks

Creates a new webhook for a project.

Request Bodyjson

{
  "projectId": "proj_abc123",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["run.completed", "run.failed"],
  "headers": { "X-Custom-Header": "value" },
  "secret": "whsec_your-webhook-secret"
}

projectIdstringRequired
Project this webhook belongs to.
urlstringRequired
The URL to send webhook payloads to.
eventsstring[]Required
Events to subscribe to. Options: run.completed, run.failed.
headersobject
Custom headers to include in webhook requests.
secretstring
Webhook secret for request signature verification.

Responsejson

{
  "id": "wh_def456",
  "projectId": "proj_abc123",
  "url": "https://hooks.slack.com/services/T00/B00/xxx",
  "events": ["run.completed", "run.failed"],
  "isActive": true,
  "createdAt": "2026-03-19T10:00:00Z"
}

Update a Webhook

PATCH /api/webhooks/:id

Updates a webhook's URL, events, headers, secret, or active status.

Request Bodyjson

{
  "url": "https://hooks.slack.com/services/T00/B00/new-url",
  "events": ["run.failed"],
  "isActive": true
}

urlstring
Updated webhook URL.
eventsstring[]
Updated event subscriptions.
headersobject
Updated custom headers.
secretstring
Updated webhook secret.
isActiveboolean
Set to false to deactivate without deleting.

Responsejson

{
  "id": "wh_def456",
  "url": "https://hooks.slack.com/services/T00/B00/new-url",
  "events": ["run.failed"],
  "isActive": true,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Delete a Webhook

DELETE /api/webhooks/:id

Permanently deletes a webhook.

Example Requestbash

curl -X DELETE https://app.euriqa.dev/api/webhooks/wh_def456 \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Project Settings

Configure per-project settings including data retention, flakiness thresholds, and auto-quarantine behavior.

Get Project Settings

GET /api/projects/:id/settings

Returns the current settings for a project.

Example Requestbash

curl -X GET https://app.euriqa.dev/api/projects/proj_abc123/settings \
  -H "X-API-Key: your-api-key"

Responsejson

{
  "projectId": "proj_abc123",
  "dataRetentionDays": 90,
  "flakinessThreshold": 0.3,
  "autoQuarantineEnabled": true,
  "updatedAt": "2026-03-15T08:00:00Z"
}

Update Project Settings

PATCH /api/projects/:id/settings

Updates project settings. Only the provided fields are updated.

Request Bodyjson

{
  "dataRetentionDays": 180,
  "flakinessThreshold": 0.5,
  "autoQuarantineEnabled": false
}

dataRetentionDaysnumber
Number of days to retain test data. Default: 90.
flakinessThresholdnumber
Flakiness score threshold for flagging tests (0 to 1). Default: 0.3.
autoQuarantineEnabledboolean
Whether to automatically quarantine tests exceeding the flakiness threshold.

Responsejson

{
  "projectId": "proj_abc123",
  "dataRetentionDays": 180,
  "flakinessThreshold": 0.5,
  "autoQuarantineEnabled": false,
  "updatedAt": "2026-03-19T10:05:00Z"
}

Error Responses

All error responses follow a consistent JSON format with an error code and human-readable message.

Error Formatjson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'projectId' is required",
    "details": {
      "field": "projectId",
      "reason": "required"
    }
  }
}

Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded.
`201`	Created	Resource created successfully.
`400`	Bad Request	Invalid request body or parameters. Check the error message for details.
`401`	Unauthorized	Missing or invalid authentication. Verify your API key or session token.
`403`	Forbidden	Authenticated but insufficient permissions for the requested action.
`404`	Not Found	The requested resource does not exist.
`413`	Payload Too Large	Uploaded file exceeds the size limit for its artifact type.
`429`	Too Many Requests	Rate limit exceeded. Retry after the delay specified in the Retry-After header.
`500`	Internal Server Error	Unexpected server error. Contact support if the issue persists.

Rate Limits

API requests are rate-limited per API key to ensure platform stability. When a rate limit is exceeded, requests return a 429 status with a Retry-After header indicating when to retry.

Endpoint Group	Rate Limit	Window
Test Runs (read)	100 requests	Per minute
Test Runs (write)	30 requests	Per minute
Tests (read)	200 requests	Per minute
Tests (write)	60 requests	Per minute
File Uploads	30 requests	Per minute
Projects / Teams	60 requests	Per minute
API Keys / Webhooks	30 requests	Per minute
Flakiness	60 requests	Per minute

Rate limits are applied per API key. If you need higher limits, contact us at support@euriqa.dev.