API Reference

TestBro exposes a REST API for managing projects, test cases, and test runs. All endpoints (unless noted) require authentication via a Bearer token in the Authorization header.

Authorization: Bearer <your-api-token>

Base URL: https://your-instance.com (or http://localhost:3024 for local development).

---

Health Check

GET /api/health

Check if the API is running. No authentication required.

Response:

{ "status": "ok" }

---

Authentication

POST /api/auth/register

Create a new user account. No authentication required.

Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePassword123"
}

POST /api/auth/login

Log in and receive a session token.

Body:

{
  "email": "john@example.com",
  "password": "SecurePassword123"
}

POST /api/auth/logout

Log out the current session.

GET /api/auth/validate

Validate an API token and return user info.

Headers: Authorization: Bearer <token>

Response:

{
  "user": {
    "id": "user-id",
    "email": "john@example.com",
    "name": "John Doe"
  }
}

---

API Tokens

GET /api/auth/tokens

List all API tokens for the authenticated user.

POST /api/auth/tokens

Create a new API token.

Body:

{
  "name": "CI/CD Token"
}

DELETE /api/auth/tokens/:id

Delete a specific API token.

---

Projects

GET /api/projects

List all projects for the authenticated user.

Response:

{
  "projects": [
    {
      "id": "project-id",
      "name": "My App",
      "description": "Main application tests",
      "_count": { "testCases": 12 }
    }
  ]
}

POST /api/projects

Create a new project.

Body:

{
  "name": "My App",
  "description": "Optional description"
}

GET /api/projects/:id

Get a single project by ID.

PATCH /api/projects/:id

Update a project.

---

Test Cases

GET /api/projects/:id/test-cases

List all test cases in a project.

POST /api/projects/:id/test-cases/bulk

Bulk create test cases.

Body:

{
  "testCases": [
    {
      "name": "User can log in",
      "description": "Verify login flow",
      "steps": [
        {
          "action": "navigate",
          "description": "Go to login page",
          "value": "/login"
        },
        {
          "action": "type",
          "description": "Enter email",
          "target": { "selector": "input[name='email']" },
          "value": "user@example.com"
        }
      ]
    }
  ],
  "deduplicationMode": "smart_merge"
}

Deduplication modes:

• skip -- Skip test cases that already exist
• force -- Create all test cases regardless of duplicates
• smart_merge -- Merge similar test cases intelligently

GET /api/projects/:id/test-cases/:tcId

Get a single test case.

PATCH /api/projects/:id/test-cases/:tcId

Update a test case.

DELETE /api/projects/:id/test-cases/:tcId

Delete a test case.

POST /api/projects/:id/test-cases/:tcId/learn-selectors

Save learned selectors for a test case's steps.

POST /api/projects/:id/test-cases/compare

Compare new test cases against existing ones for deduplication.

---

Test Case Generation

POST /api/projects/:id/generate

Generate test cases from a text description or requirements document using AI.

Body:

{
  "content": "The login page has an email field, password field, and submit button. Users should be able to log in with valid credentials and see an error for invalid ones."
}

Response:

{
  "testCases": [...],
  "count": 3
}

---

Test Runs

POST /api/projects/:id/runs

Create a new test run.

Body:

{
  "testCaseIds": ["tc-1", "tc-2"],
  "mode": "hybrid",
  "url": "https://your-app.com"
}

GET /api/runs/:id

Get details of a specific test run.

POST /api/runs/:id/results

Submit test results for a run.

POST /api/runs/:id/execute

Execute a test run server-side.

GET /api/runs/:id/events

Stream run events via Server-Sent Events (SSE).

---

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes:

Next Steps

• Authentication -- Token management
• CLI Reference -- CLI commands that use these endpoints
• CI/CD Integration -- Automating API calls in pipelines