API Reference

Base URL: https://app.greenrun.dev/api/v1

These endpoints manage test data and record results — they do not trigger Claude to run tests. Test execution happens in Claude Code via the /greenrun slash command or MCP tools, which use this API to report when runs start and finish.

Authentication #

All API requests require a Bearer token sent in the Authorization header. Sign up to create and manage tokens.

Request Header

Authorization: Bearer your-api-token
POST /tokens

Create a new API token.

Body

{ "name": "CI Pipeline" }
GET /tokens

List all API tokens for the authenticated user.

DELETE /tokens/{token_id}

Revoke an API token.

Projects #

Projects group related tests, pages, and tags together. Each project typically maps to one application or website.

GET /projects

List all projects for the authenticated user.

Response

{ "projects": [{ "id": "uuid", "name": "My App", "base_url": "https://myapp.com", "tests_count": 5, "pages_count": 3 }] }
POST /projects

Create a new project.

Body

{ "name": "My App", "base_url": "https://myapp.com", "description": "Production website" }

name is required. base_url and description are optional.

GET /projects/{project_id}

Get project details including test and page counts.

PUT /projects/{project_id}

Update a project. All fields are optional.

Body

{ "name": "Updated Name", "base_url": "https://new.example.com" }
DELETE /projects/{project_id}

Delete a project and all associated pages, tests, tags, and runs.

Pages #

Pages represent URL paths within your application. Link tests to pages to organise coverage and enable impact analysis with the sweep endpoint.

GET /projects/{project_id}/pages

List all pages in a project with linked test counts.

Response

{ "pages": [{ "id": "uuid", "url": "/login", "name": "Login Page", "tests_count": 2 }] }
POST /projects/{project_id}/pages

Register a new page in a project.

Body

{ "url": "/checkout", "name": "Checkout Page" }

url is required and must be unique within the project. name is optional.

PUT /pages/{page_id}

Update a page URL or name.

Body

{ "url": "/new-url", "name": "New Name" }
DELETE /pages/{page_id}

Delete a page and unlink it from all tests.

Tests #

Tests contain plain-text instructions that Claude will execute step by step in the browser. Organise tests with pages and tags to filter and group them.

GET /projects/{project_id}/tests

List all tests in a project. Includes latest run status, linked pages, and tags.

Response

{
  "tests": [{
    "id": "uuid",
    "name": "User can log in",
    "status": "active",
    "pages": [{ "id": "uuid", "url": "/login", "name": "Login" }],
    "tags": [{ "id": "uuid", "name": "smoke" }],
    "latest_run": { "id": "uuid", "status": "passed", "completed_at": "..." }
  }]
}
POST /projects/{project_id}/tests

Create a new test case.

Body

{
  "name": "User can log in",
  "instructions": "1. Navigate to /login\n2. Enter test@example.com and password\n3. Click Sign In\n4. Verify the dashboard heading is visible",
  "status": "active",
  "page_ids": ["uuid1", "uuid2"],
  "tags": ["smoke", "auth"]
}

name and instructions are required. status defaults to active. page_ids and tags are optional. Tags are created automatically if they don't exist in the project.

GET /tests/{test_id}

Get full test details including instructions, pages, tags, and the 10 most recent runs.

PUT /tests/{test_id}

Update a test. All fields are optional. Providing page_ids or tags replaces existing associations.

Body

{
  "name": "Updated name",
  "instructions": "Updated instructions...",
  "status": "archived",
  "page_ids": ["uuid1"],
  "tags": ["regression"]
}
DELETE /tests/{test_id}

Delete a test and all its run history.

Test Runs #

Runs track individual executions of a test. Start a run before executing instructions, then complete it with the result. The MCP server and slash commands handle this automatically.

POST /tests/{test_id}/runs

Start a new test run. Sets status to running and records the start time.

Response

{ "run": { "id": "uuid", "status": "running", "started_at": "2026-02-10T14:30:00Z" } }
PUT /runs/{run_id}

Complete a test run with results. Duration is calculated automatically.

Body

{ "status": "passed", "result": "All assertions passed successfully" }

status must be passed, failed, or error. result is an optional summary.

GET /tests/{test_id}/runs

List run history for a test, newest first. Paginated (20 per page).

GET /runs/{run_id}

Get details of a specific test run.

Sweep #

Sweep performs impact analysis by finding tests linked to specific pages. Use it after making code changes to determine which tests need re-running. The /greenrun-sweep command automates this by mapping git changes to pages.

GET /projects/{project_id}/sweep

Find active tests affected by specific pages.

Query Parameters

pages[]=/login&pages[]=/checkout   (exact URLs)
url_pattern=/checkout*              (glob pattern)

Response

{ "tests": [...], "matched_pages": ["/login", "/checkout"], "test_count": 3 }

Provide either pages[] or url_pattern, not both. Only returns active tests.