API Endpoints

REST API

Health Check

GET /health

Returns the health status of the server.

Response:

{
  "status": "healthy",
  "time": "2026-02-23T14:00:00+01:00"
}

Execute Test Suite

POST /api/v1/tests/execute
Content-Type: application/json

{
  "api_key": "your_api_key (optional)",
  "voiceflow_subdomain": "your_custom_subdomain (optional)",
  "voiceflow_api_url": "https://custom-api-host (optional)",
  "voiceflow_runtime_url": "https://custom-runtime-host (optional)",
  "voiceflow_analytics_url": "https://custom-analytics-host (optional)",
  "suite": {
    "name": "Example Suite",
    "description": "Suite used as an example",
    "environment_name": "production",
    "tests": [
      {
        "id": "test_1",
        "test": {
          "name": "Example test",
          "description": "These are some tests",
          "interactions": [
            {
              "id": "test_1_1",
              "user": {
                "type": "text",
                "text": "hi"
              },
              "agent": {
                "validate": [
                  {
                    "type": "contains",
                    "value": "hello"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

Response (202 Accepted):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "started_at": "2023-01-01T00:00:00Z",
  "logs": ["Test execution started"]
}

Executes a test suite asynchronously and returns an execution ID for tracking. The suite configuration and tests are embedded directly in the request body, making the API more HTTP-friendly and eliminating the need for file system access.

Request Parameters

• api_key (optional): Override the global Voiceflow API key for this specific test execution
• voiceflow_subdomain (optional): Override the global Voiceflow subdomain for this specific test execution. This allows you to test against different Voiceflow environments or custom subdomains without affecting the global configuration
• voiceflow_api_url (optional): Custom base URL for the Voiceflow creator-api. Takes priority over voiceflow_subdomain
• voiceflow_runtime_url (optional): Custom base URL for the Voiceflow general-runtime. Takes priority over voiceflow_subdomain
• voiceflow_analytics_url (optional): Custom base URL for the Voiceflow analytics-api. Takes priority over voiceflow_subdomain
• suite: The test suite configuration containing the test definitions

Using Custom Subdomains

When you specify a voiceflow_subdomain, the API will use that subdomain for all interactions in the test suite. For example:

• If you set "voiceflow_subdomain": "my-custom-env", requests will be sent to https://general-runtime.my-custom-env.voiceflow.com
• If you omit this field, the global subdomain configuration will be used
• This is particularly useful for testing against staging environments or customer-specific deployments

Using Custom URLs (Ephemeral Environments)

For ephemeral or non-standard environments where the URL pattern differs from <service>.<subdomain>.voiceflow.com, use the custom URL parameters:

{
  "api_key": "VF.DM.YOUR_API_KEY",
  "voiceflow_api_url": "https://your-custom-api.example.com",
  "voiceflow_runtime_url": "https://your-custom-runtime.example.com",
  "voiceflow_analytics_url": "https://your-custom-analytics.example.com",
  "suite": { ... }
}

These take priority over voiceflow_subdomain. You only need to set the ones your tests require.

Get Test Status

GET /api/v1/tests/status/{execution_id}

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "started_at": "2023-01-01T00:00:00Z",
  "completed_at": "2023-01-01T00:05:00Z",
  "logs": [
    "Starting test suite execution...",
    "Running Test ID: example_test",
    "Test suite execution completed successfully"
  ]
}

Retrieves the current status and logs of a test execution.

Cancel Test Execution

POST /api/v1/tests/cancel/{execution_id}

Cancels a running test execution.

Response (200 OK):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "cancelled",
  "started_at": "2023-01-01T00:00:00Z",
  "completed_at": "2023-01-01T00:02:30Z",
  "logs": [
    "Starting test suite execution...",
    "Test suite execution cancelled"
  ]
}

Error Responses:

• 404 Not Found: No execution with the given ID
• 409 Conflict: Execution is not running (already completed, failed, or cancelled)

System Information

GET /api/v1/system/info

Response:

{
  "version": "1.0.0",
  "go_version": "go1.20.0",
  "os": "linux",
  "arch": "amd64"
}

Returns system information about the running server instance.

WebSocket API

Connect to ws://localhost:8080/ws for a persistent connection with real-time log streaming. The WebSocket endpoint exposes the same functionality as the REST API but pushes log lines as they happen instead of requiring polling.

Protocol

All messages are JSON objects.

Client → Server:

Action	Description	Fields
execute	Start a test suite	{ "action": "execute", "data": <TestExecutionRequest> }
cancel	Cancel a running execution	{ "action": "cancel", "id": "<execution-id>" }
status	Get execution status	{ "action": "status", "id": "<execution-id>" }

Server → Client:

Type	Description
log	Real-time log line: { "type": "log", "id": "...", "message": "..." }
status	Status update: { "type": "status", "id": "...", "data": <TestStatusResponse> }
result	Final result when execution finishes: { "type": "result", "id": "...", "data": <TestStatusResponse> }
error	Error message: { "type": "error", "message": "..." }

OpenAPI/Swagger Documentation

Once the server is running, you can access the interactive API documentation at:

http://localhost:8080/swagger/index.html