External API¶

The VibeTesting External API lets you trigger test executions (immediately or on a schedule), poll for status, stop running executions, and cancel scheduled runs from any third-party system.

Authentication¶

Include your API token in every request using one of these methods:

Header: Authorization: api-key <token>
Query parameter: ?api-key=<token>

You can find your API token in the API section of the VibeTesting dashboard.

Base URL¶

https://app.vibetesting.me/api/external/

Endpoints¶

Run tests¶

Create a new execution, or schedule one for later.

curl -X POST "https://app.vibetesting.me/api/external/run-tests/" \
  -H "Authorization: api-key YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_type": "guided",
    "tests": [
      {"name": "teacher signup", "steps": "signup as a teacher, log out and signin with the new details. Verify success signin"},
      {"name": "teacher wrong credentials", "steps": "signin as a teacher with wrong credentials. Verify unsuccessful signin"}
    ],
    "login": {"login_needed": true, "identifier": "user@ex.com", "password": "secret"},
    "general_instructions": "Focus on checkout, search. Focus on error handling",
    "flows_count": 3,
    "max_steps_per_flow": 15,
    "should_send_report": false,
    "should_stop_existing": false,
    "allow_parallel": false,
    "schedule_at": "2026-04-04T02:00:00+03:00",
    "repeat": "weekly",
    "repeat_count": 4,
    "timezone": "Asia/Jerusalem"
  }'

Parameters

execution_type (required) — one of:
- guided — user-provided Tests Guidelines (flow goals or step-by-step). steps can be a string or a list.
- exploration — free-roaming exploration with optional general_instructions
tests — array of test objects (guided mode), each with name and steps
login — optional login credentials (login_needed, identifier, password)
focus_areas — optional list of areas to focus on
max_steps_per_flow — maximum steps per flow
flows_count — number of exploration flows (exploration mode)
general_instructions — optional global instructions/constraints/known issues applied to the run (distinct from per-test steps)
should_send_report — whether to email a report when done
should_stop_existing — stop any currently running execution before starting
allow_parallel — enable batched execution for parallel runs
schedule_at — ISO 8601 datetime to schedule the run instead of starting immediately (e.g. 2026-04-04T02:00:00+03:00)
repeat — recurrence interval: once, daily, or weekly
repeat_count — number of occurrences for a recurring schedule
timezone — IANA timezone string (e.g. Asia/Jerusalem, America/New_York). Defaults to the user's configured timezone

Response — immediate run

{
  "status": "success",
  "execution_ids": [123, 124]
}

Response — scheduled run

{
  "status": "success",
  "schedule_id": "....",
  "execution_ids": [123, 124, 125, 126],
  "message": "..."
}

Response — failure

{
  "status": "fail",
  "reason": "..."
}

Run suite¶

Re-run an existing suite by its ID, immediately or on a schedule.

curl -X POST "https://app.vibetesting.me/api/external/run-suite/" \
  -H "Authorization: api-key YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "suite_id": 123,
    "should_send_report": false,
    "schedule_at": "2026-04-04T02:00:00+03:00",
    "repeat": "weekly",
    "repeat_count": 4,
    "timezone": "Asia/Jerusalem"
  }'

Parameters

suite_id (required) — the ID of the suite to re-run
should_send_report — whether to email a report when done
schedule_at — ISO 8601 datetime to schedule the run instead of starting immediately (e.g. 2026-04-04T02:00:00+03:00)
repeat — recurrence interval: once, daily, or weekly
repeat_count — number of occurrences for a recurring schedule
timezone — IANA timezone string (e.g. Asia/Jerusalem, America/New_York). Defaults to the user's configured timezone

Response — immediate run

{
  "status": "success",
  "execution_ids": [123]
}

Response — scheduled run

{
  "status": "success",
  "schedule_id": "....",
  "execution_ids": [123, 124],
  "message": "..."
}

Response — failure

{
  "status": "fail",
  "reason": "..."
}

Get execution status¶

Poll for the current status of an execution.

curl -X POST "https://app.vibetesting.me/api/external/execution-status/" \
  -H "Authorization: api-key YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": 456,
    "is_get_full_report_link": true
  }'

Parameters

execution_id (required) — integer execution ID
is_get_full_report_link — when true and the execution is done, full_report_link in the response returns a PDF URL. Otherwise it is an empty string

Response — success

{
  "status": "success",
  "execution_state": "done",
  "start_time": "...",
  "end_time": "...",
  "suite_name": "...",
  "number_of_tests": 12,
  "number_of_done_tests": 12,
  "number_of_passed_tests": 10,
  "number_of_failed_tests": 2,
  "detailed_status": "...",
  "full_report_link": "..."
}

execution_state is one of done, running, or processing.

Response — failure

{
  "status": "fail",
  "reason": "..."
}

Stop execution or cancel schedule¶

Stop a running execution:

curl -X POST "https://app.vibetesting.me/api/external/stop-execution/" \
  -H "Authorization: api-key YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "execution_id": 456
  }'

Cancel a scheduled run by its schedule ID:

curl -X POST "https://app.vibetesting.me/api/external/stop-execution/" \
  -H "Authorization: api-key YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "SCHEDULE_UUID",
    "cancel_scheduled": true
  }'

Parameters

execution_id — the ID of the execution to stop (for stopping a running execution)
schedule_id — the UUID of the schedule to cancel (for cancelling a scheduled run)
cancel_scheduled — set to true when cancelling a schedule

Response — execution stopped

{
  "status": "success",
  "message": "Execution stopped"
}

Response — schedule cancelled

{
  "status": "success",
  "schedule_id": "....",
  "canceled_execution_count": 4,
  "message": "..."
}

Response — failure

{
  "status": "fail",
  "reason": "..."
}