Test Management API

These endpoints cover the core of ProvaLab.io: creating projects, writing test cases, organizing them into plans, executing runs, and recording results.

Projects

List projects

GET /api/v1/organizations/{organization_id}/projects

Parameter	In	Type	Required	Description
`organization_id`	path	integer	Yes	Organization ID
`page`	query	integer	No	Page number (default: 1)
`page_size`	query	integer	No	Items per page (default: 20, max: 100)
`status`	query	string	No	Filter: `active`, `archived`, `completed`
`search`	query	string	No	Search in name and description

curl https://your-tms-instance.com/api/v1/organizations/1/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "items": [
    {
      "id": 1,
      "name": "E-Commerce Platform",
      "slug": "ecommerce",
      "description": "Main e-commerce application",
      "status": "active",
      "created_at": "2025-11-15T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

Create a project

POST /api/v1/organizations/{organization_id}/projects

Field	Type	Required	Description
`name`	string	Yes	Project name
`slug`	string	No	URL-friendly identifier (auto-generated if omitted)
`description`	string	No	Project description
`status`	string	No	`active` (default), `archived`, `completed`
`settings`	object	No	Project-level settings

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-Commerce Platform",
    "slug": "ecommerce",
    "description": "Main e-commerce application",
    "settings": {
      "enable_ci_integration": true,
      "default_test_environment": "staging"
    }
  }'

Response 201 Created

{
  "id": 1,
  "organization_id": 1,
  "name": "E-Commerce Platform",
  "slug": "ecommerce",
  "description": "Main e-commerce application",
  "status": "active",
  "created_by_id": 1,
  "created_at": "2025-11-15T10:00:00Z",
  "updated_at": "2025-11-15T10:00:00Z"
}

Get a project

GET /api/v1/organizations/{organization_id}/projects/{project_id}

curl https://your-tms-instance.com/api/v1/organizations/1/projects/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "id": 1,
  "organization_id": 1,
  "name": "E-Commerce Platform",
  "slug": "ecommerce",
  "description": "Main e-commerce application",
  "status": "active",
  "created_by_id": 1,
  "created_at": "2025-11-15T10:00:00Z",
  "updated_at": "2025-11-15T10:00:00Z",
  "members_count": 5,
  "test_cases_count": 150,
  "modules": [
    {
      "id": 1,
      "name": "Authentication",
      "description": "User authentication module"
    }
  ]
}

Update a project

PUT /api/v1/organizations/{organization_id}/projects/{project_id}

curl -X PUT https://your-tms-instance.com/api/v1/organizations/1/projects/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-Commerce Platform (v2)",
    "description": "Updated e-commerce platform"
  }'

Delete a project

DELETE /api/v1/organizations/{organization_id}/projects/{project_id}

curl -X DELETE https://your-tms-instance.com/api/v1/organizations/1/projects/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content

Test cases

List test cases

GET /api/v1/test-management/cases

Parameter	In	Type	Required	Description
`test_suite_id`	query	integer	No	Filter by suite
`lifecycle_status`	query	string	No	`draft`, `review`, `approved`, `deprecated`
`search`	query	string	No	Search in title and description
`page`	query	integer	No	Page number (default: 1)
`page_size`	query	integer	No	Items per page (default: 20)

curl "https://your-tms-instance.com/api/v1/test-management/cases?test_suite_id=1&lifecycle_status=approved" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "items": [
    {
      "id": 1,
      "title": "Verify successful login with valid credentials",
      "priority": "high",
      "type": "functional",
      "lifecycle_status": "approved",
      "created_at": "2025-11-15T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

Create a test case

POST /api/v1/test-management/cases?test_suite_id={suite_id}

Field	Type	Required	Description
`title`	string	Yes	Test case title
`description`	string	No	Detailed description
`priority`	string	No	`low`, `medium`, `high`, `critical`
`type`	string	No	`functional`, `regression`, `smoke`, `performance`, `security`
`lifecycle_status`	string	No	`draft` (default)
`preconditions`	string	No	Required setup before test execution
`steps`	array	No	Ordered test steps (see below)
`expected_result`	string	No	Overall expected outcome
`tags`	array	No	Tags for categorization

Each step in the steps array:

Field	Type	Required	Description
`step_number`	integer	Yes	Step order (1, 2, 3...)
`action`	string	Yes	What to do
`expected_result`	string	Yes	What should happen

curl -X POST "https://your-tms-instance.com/api/v1/test-management/cases?test_suite_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Verify successful login with valid credentials",
    "description": "Test that users can log in with correct email and password",
    "priority": "high",
    "type": "functional",
    "preconditions": "User account exists in the system",
    "steps": [
      {
        "step_number": 1,
        "action": "Navigate to login page",
        "expected_result": "Login form is displayed"
      },
      {
        "step_number": 2,
        "action": "Enter valid email and password",
        "expected_result": "Credentials are accepted"
      },
      {
        "step_number": 3,
        "action": "Click login button",
        "expected_result": "User is redirected to dashboard"
      }
    ],
    "expected_result": "User successfully logs in and sees dashboard",
    "tags": ["authentication", "login", "smoke"]
  }'

Response 201 Created

{
  "id": 1,
  "test_suite_id": 1,
  "title": "Verify successful login with valid credentials",
  "description": "Test that users can log in with correct email and password",
  "priority": "high",
  "type": "functional",
  "lifecycle_status": "draft",
  "created_by_id": 1,
  "created_at": "2025-11-15T10:00:00Z",
  "steps": [
    {
      "step_number": 1,
      "action": "Navigate to login page",
      "expected_result": "Login form is displayed"
    }
  ]
}

Get a test case

GET /api/v1/test-management/cases/{case_id}

curl https://your-tms-instance.com/api/v1/test-management/cases/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update a test case

PUT /api/v1/test-management/cases/{case_id}

curl -X PUT https://your-tms-instance.com/api/v1/test-management/cases/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated test case title",
    "priority": "critical"
  }'

Change lifecycle status

Move a test case through the review workflow: draft -> review -> approved -> deprecated.

POST /api/v1/test-management/cases/{case_id}/lifecycle

Field	Type	Required	Description
`new_status`	string	Yes	Target status
`comment`	string	No	Reason for the status change

curl -X POST https://your-tms-instance.com/api/v1/test-management/cases/1/lifecycle \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_status": "approved",
    "comment": "Reviewed and approved by QA lead"
  }'

Delete a test case

DELETE /api/v1/test-management/cases/{case_id}

curl -X DELETE https://your-tms-instance.com/api/v1/test-management/cases/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204 No Content

Test suites

Test suites group related test cases together (e.g., "Login Tests", "Payment Tests").

List test suites

GET /api/v1/organizations/{organization_id}/test-suites?module_id={module_id}

curl "https://your-tms-instance.com/api/v1/organizations/1/test-suites?module_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a test suite

POST /api/v1/test-management/suites?module_id={module_id}

curl -X POST "https://your-tms-instance.com/api/v1/test-management/suites?module_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Authentication Tests",
    "description": "Test suite for login, logout, and password management",
    "priority": "high"
  }'

Response 201 Created

{
  "id": 1,
  "module_id": 1,
  "name": "User Authentication Tests",
  "description": "Test suite for login, logout, and password management",
  "priority": "high",
  "created_at": "2025-11-15T10:00:00Z"
}

Test plans

Test plans define which test cases to execute for a release, sprint, or testing cycle.

List test plans

GET /api/v1/organizations/{organization_id}/test-plans

Parameter	In	Type	Required	Description
`project_id`	query	integer	No	Filter by project
`status`	query	string	No	`draft`, `in_review`, `approved`, `active`, `completed`, `archived`
`test_plan_type`	query	string	No	`smoke`, `sanity`, `regression`, `system`, `integration`, `uat`, `performance`, `security`, `e2e`
`priority`	query	string	No	`low`, `medium`, `high`, `critical`

curl "https://your-tms-instance.com/api/v1/organizations/1/test-plans?project_id=1&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a test plan

POST /api/v1/organizations/{organization_id}/test-plans

Field	Type	Required	Description
`name`	string	Yes	Test plan name
`project_id`	integer	Yes	Project ID
`test_plan_type`	string	Yes	See type options above
`priority`	string	No	`low`, `medium` (default), `high`, `critical`
`description`	string	No	Plan description
`objectives`	string	No	Testing objectives
`target_pass_rate`	number	No	Target pass rate (default: 95.0)

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-plans \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 12 Regression",
    "project_id": 1,
    "test_plan_type": "regression",
    "priority": "high",
    "description": "Full regression for Sprint 12 release",
    "target_pass_rate": 95.0
  }'

Response 201 Created

{
  "id": 1,
  "name": "Sprint 12 Regression",
  "project_id": 1,
  "test_plan_type": "regression",
  "status": "draft",
  "priority": "high",
  "target_pass_rate": 95.0,
  "created_at": "2025-11-15T10:00:00Z"
}

Test runs

Test runs are executions of a test plan or a set of test cases.

Create a test run

POST /api/v1/organizations/{organization_id}/test-runs

Field	Type	Required	Description
`name`	string	Yes	Run name
`project_id`	integer	Yes	Project ID
`test_plan_id`	integer	No	Test plan ID
`environment`	string	No	`dev`, `staging`, `prod`
`test_case_ids`	array	No	Specific test case IDs to include
`assigned_to_id`	integer	No	Assignee user ID
`configuration`	object	No	Run configuration (browser, OS, build number)

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 10 Regression",
    "project_id": 1,
    "test_plan_id": 1,
    "environment": "staging",
    "test_case_ids": [1, 2, 3, 4, 5],
    "configuration": {
      "browser": "chrome",
      "os": "linux",
      "build_number": "1.2.3"
    }
  }'

Response 201 Created

{
  "id": 1,
  "name": "Sprint 10 Regression",
  "project_id": 1,
  "status": "pending",
  "environment": "staging",
  "total_test_cases": 5,
  "executed": 0,
  "passed": 0,
  "failed": 0,
  "skipped": 0,
  "created_at": "2025-11-15T10:00:00Z"
}

Start a test run

POST /api/v1/organizations/{organization_id}/test-runs/{run_id}/start

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/start \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "id": 1,
  "status": "running",
  "started_at": "2025-11-15T10:00:00Z"
}

Get test run details

GET /api/v1/organizations/{organization_id}/test-runs/{run_id}

curl https://your-tms-instance.com/api/v1/organizations/1/test-runs/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "id": 1,
  "name": "Sprint 10 Regression",
  "project_id": 1,
  "status": "running",
  "environment": "staging",
  "total_test_cases": 5,
  "executed": 3,
  "passed": 2,
  "failed": 1,
  "skipped": 0,
  "progress": 60,
  "started_at": "2025-11-15T10:00:00Z",
  "results": [
    {
      "test_case_id": 1,
      "status": "passed",
      "duration": 2.5,
      "executed_at": "2025-11-15T10:01:00Z"
    },
    {
      "test_case_id": 2,
      "status": "failed",
      "duration": 3.2,
      "error_message": "Assertion failed: Expected 'Welcome' but got 'Error'",
      "executed_at": "2025-11-15T10:02:00Z"
    }
  ]
}

Record a test result

Submit the result for an individual test case within a run.

POST /api/v1/organizations/{organization_id}/test-runs/{run_id}/results

Field	Type	Required	Description
`test_case_id`	integer	Yes	Test case ID
`status`	string	Yes	`passed`, `failed`, `skipped`, `blocked`
`duration`	number	No	Execution time in seconds
`executed_by_id`	integer	No	User who ran the test
`executed_at`	string	No	ISO 8601 timestamp
`comment`	string	No	Notes about the result
`artifacts`	array	No	Screenshots, logs, etc.

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/results \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_id": 1,
    "status": "passed",
    "duration": 2.5,
    "executed_by_id": 1,
    "comment": "Test passed on first attempt",
    "artifacts": [
      {
        "type": "screenshot",
        "url": "https://storage.example.com/screenshots/run1-tc1.png"
      }
    ]
  }'

Response 201 Created

{
  "id": 1,
  "test_run_id": 1,
  "test_case_id": 1,
  "status": "passed",
  "duration": 2.5,
  "executed_at": "2025-11-15T10:01:00Z"
}

Complete a test run

Mark a test run as finished.

POST /api/v1/organizations/{organization_id}/test-runs/{run_id}/complete

curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/complete \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "id": 1,
  "status": "completed",
  "completed_at": "2025-11-15T11:00:00Z",
  "summary": {
    "total": 5,
    "passed": 4,
    "failed": 1,
    "skipped": 0,
    "pass_rate": 80.0
  }
}

Practical example: end-to-end workflow

Here is a complete workflow showing how to create a project, add a test case, run it, and record the result:

# 1. Create a project
curl -X POST https://your-tms-instance.com/api/v1/organizations/1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "slug": "myapp"}'

# 2. Create a test case (assuming test suite ID 1 exists)
curl -X POST "https://your-tms-instance.com/api/v1/test-management/cases?test_suite_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Homepage loads within 3 seconds",
    "priority": "high",
    "type": "performance"
  }'

# 3. Create a test run
curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quick Smoke Test",
    "project_id": 1,
    "environment": "staging",
    "test_case_ids": [1]
  }'

# 4. Start the run
curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/start \
  -H "Authorization: Bearer YOUR_TOKEN"

# 5. Record the result
curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/results \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_id": 1,
    "status": "passed",
    "duration": 1.8
  }'

# 6. Complete the run
curl -X POST https://your-tms-instance.com/api/v1/organizations/1/test-runs/1/complete \
  -H "Authorization: Bearer YOUR_TOKEN"

Next steps

Integrations API -- Set up webhooks and connect Jira, Slack, and GitHub
AI API -- Generate test cases and analyze failures with AI

Projects​

List projects​

Create a project​

Get a project​

Update a project​

Delete a project​

Test cases​

List test cases​

Create a test case​

Get a test case​

Update a test case​

Change lifecycle status​

Delete a test case​

Test suites​

List test suites​

Create a test suite​

Test plans​

List test plans​

Create a test plan​

Test runs​

Create a test run​

Start a test run​

Get test run details​

Record a test result​

Complete a test run​

Practical example: end-to-end workflow​

Next steps​

Projects

List projects

Create a project

Get a project

Update a project

Delete a project

Test cases

List test cases

Create a test case

Get a test case

Update a test case

Change lifecycle status

Delete a test case

Test suites

List test suites

Create a test suite

Test plans

List test plans

Create a test plan

Test runs

Create a test run

Start a test run

Get test run details

Record a test result

Complete a test run

Practical example: end-to-end workflow

Next steps