Test Cases API

Create, retrieve, update, and delete test cases. Supports filtering, pagination, and bulk operations.

Base URL:https://api.testably.app/v1

GET/v1/projects/:pid/test-cases

List all test cases in a project. Supports filtering by folder, priority, type, and search keywords. Results are paginated.

Query Parameters

Name	Type	Required	Description
`folder_id`	string	Optional	Filter by folder ID
`priority`	string	Optional	Filter by priority: critical, high, medium, low
`type`	string	Optional	Filter by type: functional, smoke, regression, etc.
`search`	string	Optional	Search test case titles
`page`	integer	Optional	Page number (default: 1)
`per_page`	integer	Optional	Items per page (default: 20, max: 100)

Response

{
  "data": [
    {
      "id": "tc_001",
      "title": "Login with valid credentials",
      "folder_id": "fld_auth",
      "priority": "critical",
      "type": "functional",
      "precondition": "User account exists and is active",
      "steps": [
        { "position": 1, "action": "Navigate to /login", "expected": "Login page loads" },
        { "position": 2, "action": "Enter valid email and password", "expected": "Fields populated" },
        { "position": 3, "action": "Click Sign In", "expected": "Redirect to dashboard" }
      ],
      "expected_result": "User is logged in and redirected to dashboard",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-03-20T08:30:00Z"
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20
  }
}

GET/v1/projects/:pid/test-cases/:id

Retrieve a single test case by its ID, including all steps, preconditions, and metadata.

Response

{
  "data": {
    "id": "tc_001",
    "title": "Login with valid credentials",
    "folder_id": "fld_auth",
    "priority": "critical",
    "type": "functional",
    "precondition": "User account exists and is active",
    "steps": [
      { "position": 1, "action": "Navigate to /login", "expected": "Login page loads" },
      { "position": 2, "action": "Enter valid email and password", "expected": "Fields populated" },
      { "position": 3, "action": "Click Sign In", "expected": "Redirect to dashboard" }
    ],
    "expected_result": "User is logged in and redirected to dashboard",
    "tags": ["auth", "smoke"],
    "created_by": "user_abc",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-20T08:30:00Z"
  }
}

POST/v1/projects/:pid/test-casesComing Soon

Create a new test case in the specified project. Provide the title, optional folder, priority, type, precondition, steps, and expected result.

Parameters

Name	Type	Required	Description
`title`	string	Required	Test case title
`folder_id`	string	Optional	Target folder ID
`priority`	string	Optional	Priority level: critical, high, medium, low (default: medium)
`type`	string	Optional	Test type: functional, smoke, regression, etc.
`precondition`	string	Optional	Precondition text
`steps`	array	Optional	Array of { action, expected } step objects
`expected_result`	string	Optional	Overall expected result

Request Body

{
  "title": "Forgot password sends reset email",
  "folder_id": "fld_auth",
  "priority": "high",
  "type": "functional",
  "precondition": "User has a registered email",
  "steps": [
    { "action": "Navigate to /forgot-password", "expected": "Reset form loads" },
    { "action": "Enter registered email", "expected": "Email field populated" },
    { "action": "Click Send Reset Link", "expected": "Success message shown" }
  ],
  "expected_result": "Password reset email is sent to the user"
}

Response

{
  "data": {
    "id": "tc_143",
    "title": "Forgot password sends reset email",
    "folder_id": "fld_auth",
    "priority": "high",
    "type": "functional",
    "precondition": "User has a registered email",
    "steps": [
      { "position": 1, "action": "Navigate to /forgot-password", "expected": "Reset form loads" },
      { "position": 2, "action": "Enter registered email", "expected": "Email field populated" },
      { "position": 3, "action": "Click Send Reset Link", "expected": "Success message shown" }
    ],
    "expected_result": "Password reset email is sent to the user",
    "created_at": "2026-03-29T10:00:00Z",
    "updated_at": "2026-03-29T10:00:00Z"
  }
}

PATCH/v1/projects/:pid/test-cases/:idComing Soon

Update an existing test case. Only provided fields will be modified. Steps can be replaced entirely by sending a new steps array.

Parameters

Name	Type	Required	Description
`title`	string	Optional	Updated title
`folder_id`	string	Optional	Move to different folder
`priority`	string	Optional	Updated priority
`type`	string	Optional	Updated type
`precondition`	string	Optional	Updated precondition
`steps`	array	Optional	Replacement steps array
`expected_result`	string	Optional	Updated expected result

Request Body

{
  "priority": "critical",
  "title": "Forgot password sends reset email (updated)"
}

Response

{
  "data": {
    "id": "tc_143",
    "title": "Forgot password sends reset email (updated)",
    "priority": "critical",
    "updated_at": "2026-03-29T11:30:00Z"
  }
}

DELETE/v1/projects/:pid/test-cases/:idComing Soon

Permanently delete a test case. Associated run results will be preserved but the test case reference will be removed.

Response

{
  "message": "Test case deleted successfully"
}

POST/v1/projects/:pid/test-cases/bulkComing Soon

Create multiple test cases in a single request. Useful for importing test cases from external tools or spreadsheets. Maximum 100 test cases per request.

Request Body

{
  "test_cases": [
    {
      "title": "Signup with Google OAuth",
      "folder_id": "fld_auth",
      "priority": "high",
      "type": "functional",
      "steps": [
        { "action": "Click Continue with Google", "expected": "OAuth consent screen" },
        { "action": "Select Google account", "expected": "Account created, redirect to dashboard" }
      ]
    },
    {
      "title": "Signup with email",
      "folder_id": "fld_auth",
      "priority": "high",
      "type": "functional",
      "steps": [
        { "action": "Fill signup form", "expected": "Form validated" },
        { "action": "Click Create Account", "expected": "Verification email sent" }
      ]
    }
  ]
}

Response

{
  "data": {
    "created": 2,
    "test_cases": [
      { "id": "tc_144", "title": "Signup with Google OAuth" },
      { "id": "tc_145", "title": "Signup with email" }
    ]
  }
}

Projects API Test Runs API