Exploratory

Capture findings during exploratory testing sessions. Log notes, bugs, observations, and questions, then convert promising entries into test cases.

Log entry types

note

General observation or note

bug

Potential or confirmed bug

observation

Behavioral observation

question

Open question to investigate

GET/v1/projects/:project_id/sessions

List discovery sessions

Retrieve all discovery sessions for a project.

Query parameters

Parameter	Type	Required	Description
page	number	No	Page number for pagination (default: 1)
per_page	number	No	Items per page (default: 20, max: 100)

Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.testably.app/v1/projects/proj_abc123/sessions"

Response 200 OK

{
  "data": [
    {
      "id": "sess_001",
      "title": "Checkout flow exploration",
      "description": "Testing edge cases in the payment checkout",
      "log_count": 12,
      "created_by": "user_42",
      "created_at": "2026-03-28T14:00:00Z",
      "updated_at": "2026-03-28T16:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1 }
}

POST/v1/projects/:project_id/sessions

Create session

Start a new discovery session for exploratory testing.

Request body

Parameter	Type	Required	Description
title	string	Yes	Session title
description	string	No	Optional session description or charter

Request

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Mobile responsive testing",
       "description": "Testing all pages on iOS Safari and Android Chrome"
     }' \
     "https://api.testably.app/v1/projects/proj_abc123/sessions"

Response 201 Created

{
  "id": "sess_002",
  "title": "Mobile responsive testing",
  "description": "Testing all pages on iOS Safari and Android Chrome",
  "log_count": 0,
  "created_by": "user_42",
  "created_at": "2026-03-29T09:00:00Z",
  "updated_at": "2026-03-29T09:00:00Z"
}

GET/v1/sessions/:session_id/logs

List logs in session

Retrieve all log entries within a session. Optionally filter by log type.

Query parameters

Parameter	Type	Required	Description
type	string	No	Filter by log type: note, bug, observation, or question
page	number	No	Page number for pagination (default: 1)
per_page	number	No	Items per page (default: 20, max: 100)

Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.testably.app/v1/sessions/sess_001/logs?type=bug"

Response 200 OK

{
  "data": [
    {
      "id": "log_001",
      "type": "bug",
      "content": "Payment form does not validate expiry date in MM/YY format",
      "screenshot_url": "https://cdn.testably.app/screenshots/log_001.png",
      "converted_to_tc": null,
      "created_by": "user_42",
      "created_at": "2026-03-28T14:12:00Z"
    },
    {
      "id": "log_003",
      "type": "bug",
      "content": "Discount code field accepts negative values",
      "screenshot_url": null,
      "converted_to_tc": "tc_205",
      "created_by": "user_42",
      "created_at": "2026-03-28T14:45:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 2 }
}

POST/v1/sessions/:session_id/logs

Add log entry

Add a new log entry to a discovery session.

Request body

Parameter	Type	Required	Description
type	string	Yes	Log type: note, bug, observation, or question
content	string	Yes	Log entry content (supports Markdown)
screenshot_url	string	No	URL to an attached screenshot

Request

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "observation",
       "content": "Loading spinner persists for 5+ seconds on slow 3G",
       "screenshot_url": "https://cdn.testably.app/screenshots/obs_001.png"
     }' \
     "https://api.testably.app/v1/sessions/sess_001/logs"

Response 201 Created

{
  "id": "log_013",
  "type": "observation",
  "content": "Loading spinner persists for 5+ seconds on slow 3G",
  "screenshot_url": "https://cdn.testably.app/screenshots/obs_001.png",
  "converted_to_tc": null,
  "created_by": "user_42",
  "created_at": "2026-03-29T09:20:00Z"
}

POST/v1/sessions/:session_id/logs/:log_id/convertComing Soon

Convert log to test case

Convert a discovery log entry into a formal test case. The log content is used as the test case description. The original log is updated with a reference to the new test case.

Request body

Parameter	Type	Required	Description
title	string	No	Test case title (defaults to first line of log content)
folder_id	string	No	Target folder for the new test case
priority	string	No	Priority: low, medium, high, critical

Request

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Verify expiry date validation in payment form",
       "folder_id": "folder_checkout",
       "priority": "high"
     }' \
     "https://api.testably.app/v1/sessions/sess_001/logs/log_001/convert"

Response 201 Created

{
  "test_case": {
    "id": "tc_210",
    "title": "Verify expiry date validation in payment form",
    "description": "Payment form does not validate expiry date in MM/YY format",
    "priority": "high",
    "folder_id": "folder_checkout",
    "created_at": "2026-03-29T09:30:00Z"
  },
  "log": {
    "id": "log_001",
    "converted_to_tc": "tc_210"
  }
}

Error responses

Status	Description
400	Invalid request body or query parameters
401	Missing or invalid API token
403	Insufficient permissions
404	Session or log entry not found
409	Log entry already converted to a test case
429	Rate limit exceeded (60 req/min)