🚀 Getting Started
The PathSim API provides read-only access to your organization's test data, including voice calls and web tests. All data is returned in the same format as your Test History table for easy integration.
API Base URL: https://api.pathsim.com/v1
🔐 Authentication
All API requests require authentication using your organization's API key. Include the API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY_HERE
⚠️ Security Note: Keep your API key secure and never expose it in client-side code. API keys provide read access to all workspaces in your organization.
📡 API Endpoints
GET /v1/workspaces
Retrieve all workspaces accessible to your organization.
Response Example:
{
"success": true,
"data": [
{
"id": "1c0862bb-53fb-4f38-944d-29e8586327fe",
"name": "Production Workspace",
"description": "Main production environment",
"organizationId": "712cddc4-8da1-4c61-bce0-3de10792d909",
"createdAt": "2025-01-01T00:00:00.000Z",
"isActive": true,
"isDefault": false
}
]
}
GET /v1/workspaces/{workspaceId}/sessions
Retrieve test sessions for a specific workspace. Returns data in Test History table format.
Path Parameters:
| Parameter | Type | Description |
|---|
workspaceId | string | The workspace ID to fetch sessions from |
Query Parameters:
| Parameter | Type | Description | Example |
|---|
type | string | Filter by test type | voice, web |
source | string | Filter by test source | Campaign, Ad-hoc |
objective | string | Filter by objective achievement | achieved, not_achieved |
connected | string | Filter by connection status | connected, failed, system_error, in_progress |
search | string | Search in agent names or targets | chatbot, weather |
created_from | string | Filter by start date (ISO 8601) | 2025-08-01 |
created_to | string | Filter by end date (ISO 8601) | 2025-08-31 |
sort | string | Sort field (prefix with - for desc) | -created_at, start_timestamp |
limit | integer | Number of results (max 100) | 50 |
offset | integer | Pagination offset | 0 |
Response Example:
{
"success": true,
"data": [
{
"Time": "08/08/2025 18:00",
"Test Type": "Voice",
"Objective": "Achieved",
"Connected": "Connected",
"Virtual Customer": "National Weather Service Test",
"Target": "+18316561725",
"Source": "Campaign",
"_id": "68963b44e7b3ba1e58b7c60a",
"test_id": "call_87ef5ad91dfd8bddbfb651e70c7"
},
{
"Time": "08/08/2025 14:21",
"Test Type": "Web",
"Objective": "Achieved",
"Connected": "Connected",
"Virtual Customer": "chatbot.com price finder",
"Target": "https://chatbot.com",
"Source": "Campaign",
"_id": "689607cce7b3ba1e58b7c4da",
"test_id": "test_20250808_142100_719132"
}
],
"pagination": {
"total": 475,
"limit": 50,
"offset": 0,
"hasMore": true
}
}
GET /v1/sessions/{sessionId}
Retrieve details for a single test session.
Path Parameters:
| Parameter | Type | Description |
|---|
sessionId | string | The unique identifier of the test session |
Response Example:
{
"success": true,
"data": {
// Test History table format
"Time": "08/08/2025 18:00",
"Test Type": "Voice",
"Objective": "Achieved",
"Connected": "Connected",
"Virtual Customer": "National Weather Service Test",
"Target": "+18316561725",
"Source": "Campaign",
"_id": "68963b44e7b3ba1e58b7c60a",
"test_id": "call_87ef5ad91dfd8bddbfb651e70c7",
// Additional detailed information
"duration": "4m 28s",
"recording_url": "https://api.pathsim.com/v1/sessions/SESSION_ID/recording",
"summary": "The user provided the business hours of the company...",
// Analysis flags for UI badges
"call_successful": true,
"test_successful": true,
"objective_met": true,
"reached_target_website": true, // Web tests only
"intent_achieved": true, // Web tests only
// Voice call specific fields
"transcript": "user: Good day. ABC Test Company. This is Sarah speaking...",
"to_number": "+18316561725",
"disconnection_reason": "agent_hangup",
"user_sentiment": "Positive",
"far_end_latency_stats": {
"average_ms": 180,
"min_ms": 120,
"max_ms": 320,
"valid_measurements": 18
},
// Web test specific fields (when Test Type = "Web")
"target_url": "https://example.com",
"steps": [
{
"step_number": 1,
"action": "navigate",
"target": "Navigated to the sign-in page",
"value": "Successfully reached the sign-in page",
"status": "completed",
"timestamp": 1754585255365
}
]
}
}
GET /v1/sessions/{sessionId}/recording
Access recordings for test sessions. Supports both information and direct download modes.
Path Parameters:
| Parameter | Type | Description |
|---|
sessionId | string | The unique identifier of the test session |
Query Parameters:
| Parameter | Type | Description |
|---|
download | boolean | Optional. Set to true to download the file directly |
Response Modes:
- Info mode (default): Returns JSON with branded download URL and file information
- Download mode (?download=true): Streams the recording file directly
- Consistent behavior: Both voice and web recordings work exactly the same way
Recording Info Response:
{
"success": true,
"data": {
"message": "Recording available for download",
"download_url": "https://api.pathsim.com/v1/sessions/SESSION_ID/recording?download=true",
"session_id": "SESSION_ID",
"file_type": "audio/wav", // or "video/mp4" for web tests
"instructions": "Add ?download=true to the URL to download the file directly"
}
}
Usage Examples:
# Get recording information (voice or web)
GET /v1/sessions/abc123/recording
# Download recording directly (voice or web)
GET /v1/sessions/abc123/recording?download=true
# Both voice and web recordings work the same way
GET /v1/sessions/voice456/recording
GET /v1/sessions/web789/recording?download=true
💡 Note: Both voice and web recordings have identical behavior. Use the default endpoint to get download information, then add ?download=true to trigger the actual download.
🔍 Filtering & Search
The API supports comprehensive filtering matching your Test History table columns:
| Column | Filter | Description | Example |
|---|
| Time | created_from, created_to | Date range filtering | ?created_from=2025-08-01 |
| Test Type | type | Voice or Web tests | ?type=voice |
| Objective | objective | Achievement status | ?objective=achieved |
| Connected | connected | Connection status | ?connected=connected |
| Virtual Customer | search | Search in agent names | ?search=weather |
| Target | search | Search in phone/URL | ?search=chatbot.com |
| Source | source | Campaign vs Ad-hoc | ?source=Campaign |
Available Filters
📌 Key Points:
• Source Filter: Use source=Campaign for Campaign tests, source=Ad-hoc for Ad-hoc tests
• Search Filter: Searches both Virtual Customer names and Target values
• Calculated Filters: objective and connected are processed after data retrieval
Pagination
- limit: Number of results per page (default: 50, max: 100)
- offset: Number of results to skip (default: 0)
- sort: Sort field and direction (default:
-created_at)
💡 Tip: Use search to find tests by virtual customer name or target. For example:
?search=weather finds tests with "weather" in agent name or target?search=chatbot.com finds tests targeting chatbot.com
Test History Table Format
All session data is returned in the same format as your frontend Test History table:
| Field | Type | Description | Example |
|---|
Time | string | Test start time (UTC) | "08/08/2025 18:00" |
Test Type | string | Voice or Web | "Voice" |
Objective | string | Achievement status | "Achieved" |
Connected | string | Connection status | "Connected" |
Virtual Customer | string | Agent name | "National Weather Service Test" |
Target | string | Phone number or URL | "+18316561725" |
Source | string | Campaign or Ad-hoc | "Campaign" |
_id | string | Unique session identifier | "68963b44e7b3ba1e58b7c60a" |
test_id | string | Unique test identifier | "call_87ef5ad91dfd8bddbfb651e70c7" |
Status Values
Objective: Achieved Not Achieved -- (in progress/error)
Connected: Connected Failed System Error In Progress
Source: Campaign Ad-hoc