Skip to main content

REST API

The LiveDoc Viewer exposes a REST API for querying test results, managing runs, and submitting data programmatically. All endpoints are served from the same host and port as the web UI.

Base URL: http://localhost:3100 (default)

All request and response bodies use JSON (Content-Type: application/json).

Reference​

Health Check​

GET /api/health​

Returns the server's health status. Use this to verify the viewer is running before sending test results.

curl http://localhost:3100/api/health

Response 200 OK:

{
  "status": "ok"
}

Projects​

GET /api/projects​

Lists all projects that have submitted test results.

curl http://localhost:3100/api/projects

Response 200 OK:

[
  {
    "name": "my-api",
    "environments": ["local", "ci"]
  },
  {
    "name": "my-web-app",
    "environments": ["local"]
  }
]

Hierarchy​

GET /api/hierarchy​

Returns the full project → environment → run tree structure. Useful for building navigation or dashboards on top of the viewer data.

curl http://localhost:3100/api/hierarchy

Response 200 OK:

{
  "projects": [
    {
      "name": "my-api",
      "environments": [
        {
          "name": "local",
          "runs": ["run-001", "run-002"]
        }
      ]
    }
  ]
}

Runs​

GET /api/runs​

Lists all test runs across all projects and environments.

curl http://localhost:3100/api/runs

Response 200 OK:

[
  {
    "runId": "run-001",
    "project": "my-api",
    "environment": "local",
    "startedAt": "2025-01-15T10:30:00Z",
    "status": "completed",
    "summary": {
      "features": 5,
      "scenarios": 23,
      "passed": 22,
      "failed": 1,
      "skipped": 0
    }
  }
]

GET /api/runs/:runId​

Returns the full details of a specific run, including all features, scenarios, and step results.

curl http://localhost:3100/api/runs/run-001

Response 200 OK:

{
  "runId": "run-001",
  "project": "my-api",
  "environment": "local",
  "startedAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:45Z",
  "status": "completed",
  "features": [
    {
      "title": "User Authentication",
      "tags": ["auth"],
      "scenarios": [
        {
          "title": "Successful login",
          "status": "passed",
          "steps": [
            {
              "keyword": "Given",
              "title": "a registered user",
              "status": "passed",
              "duration": 12
            }
          ]
        }
      ]
    }
  ]
}

Response 404 Not Found — if the run ID does not exist.

DELETE /api/runs/:runId​

Deletes a specific run and its associated data.

curl -X DELETE http://localhost:3100/api/runs/run-001

Response 200 OK:

{
  "deleted": "run-001"
}

Response 404 Not Found — if the run ID does not exist.

POST /api/runs​

Submit a complete test run in a single request (batch mode). The entire run payload is sent at once after all tests finish.

curl -X POST http://localhost:3100/api/runs \
  -H "Content-Type: application/json" \
  -d @results.json

Request body:

{
  "project": "my-api",
  "environment": "local",
  "features": [
    {
      "title": "Shopping Cart",
      "scenarios": [
        {
          "title": "Add item to cart",
          "status": "passed",
          "steps": [
            {
              "keyword": "Given",
              "title": "an empty cart",
              "status": "passed",
              "duration": 5
            },
            {
              "keyword": "When",
              "title": "a product is added",
              "status": "passed",
              "duration": 8
            },
            {
              "keyword": "Then",
              "title": "the cart contains '1' item",
              "status": "passed",
              "duration": 3
            }
          ]
        }
      ]
    }
  ]
}

Response 201 Created:

{
  "runId": "run-003",
  "status": "completed"
}

POST /api/runs/start​

Start a streaming run. Unlike the batch endpoint, this begins a run that receives incremental updates — scenarios and steps are posted as they complete. This is the endpoint used by real-time reporters.

curl -X POST http://localhost:3100/api/runs/start \
  -H "Content-Type: application/json" \
  -d '{"project": "my-api", "environment": "local"}'

Request body:

{
  "project": "my-api",
  "environment": "local"
}

Response 201 Created:

{
  "runId": "run-004",
  "status": "started"
}

The returned runId is used by subsequent WebSocket messages and API calls to associate incremental results with this run.

Usage Examples​

Check if the viewer is running​

curl -s http://localhost:3100/api/health | jq .status
# "ok"

List all runs and find failures​

curl -s http://localhost:3100/api/runs | jq '.[] | select(.summary.failed > 0)'

Download a run as JSON​

curl -s http://localhost:3100/api/runs/run-001 > run-001.json

Clean up old runs​

# Delete a specific run
curl -X DELETE http://localhost:3100/api/runs/run-001

See Also​