API Reference
Complete reference for the UltraVoice REST and WebSocket API. Every endpoint includes runnable curl, Python, and JavaScript examples.
ℹ️
Base URL: https://ultravoice.us.inc/api/v1 — All requests go through this gateway. Most endpoints require a bearer token: send Authorization: Bearer <access_token>. Get a token via the Authentication endpoints below.
Authentication & Workspaces
The UltraVoice API uses bearer token authentication. Start by registering a user account, then verify the OTP sent to your email, which grants you access tokens. Use these tokens (via the Authorization: Bearer <token> header) to access protected endpoints. You can also manage API keys for programmatic access and organize related resources within workspaces.
Getting Started: Registration and Login Flow
1. Call POST /auth/register with your email, password, and name to start.
2. Verify the OTP code sent to your email with POST /auth/verify-otp to receive access_token and refresh_token.
3. Use the access_token in all subsequent protected requests: -H "Authorization: Bearer <access_token>".
4. When the access token expires, call POST /auth/refresh with your refresh_token to obtain a new access_token.
5. Manage API keys and workspaces (for multi-tenant organization) with the authenticated endpoints below.
POST /auth/register
Register a new user account. Sends an OTP code to the provided email address. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "SecurePassword123!",
"first_name": "John",
"last_name": "Doe"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/register",
json={
"email": "[email protected]",
"password": "SecurePassword123!",
"first_name": "John",
"last_name": "Doe"
}
)
print(response.json())JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/register`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: "[email protected]",
password: "SecurePassword123!",
first_name: "John",
last_name: "Doe"
})
});
console.log(await response.json());Response: {"message": "OTP sent", "email": "[email protected]"}
POST /auth/verify-otp
Verify the OTP code sent to your email during registration. Returns access and refresh tokens along with user and workspace information. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/verify-otp \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"code": "123456"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/verify-otp",
json={
"email": "[email protected]",
"code": "123456"
}
)
result = response.json()
print(f"Access Token: {result['access_token']}")
print(f"User ID: {result['user']['id']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/verify-otp`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: "[email protected]",
code: "123456"
})
});
const result = await response.json();
console.log(`Access Token: ${result.access_token}`);
console.log(`User ID: ${result.user.id}`);Response: {"access_token": "<JWT>", "refresh_token": "<JWT>", "expires_in": 3600, "token_type": "Bearer", "user": {...}, "workspace": {...}}
POST /auth/resend-otp
Resend the OTP code to the user's email. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/resend-otp \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/resend-otp",
json={"email": "[email protected]"}
)
print(response.json())JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/resend-otp`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: "[email protected]"
})
});
console.log(await response.json());Response: shape unverified
POST /auth/login
Log in with email and password credentials. Returns access and refresh tokens. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "SecurePassword123!"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/login",
json={
"email": "[email protected]",
"password": "SecurePassword123!"
}
)
result = response.json()
token = result['access_token']
print(f"Token: {token}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/login`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: "[email protected]",
password: "SecurePassword123!"
})
});
const result = await response.json();
console.log(`Token: ${result.access_token}`);Response: {"access_token": "<JWT>", "refresh_token": "<JWT>", "expires_in": 3600, "token_type": "Bearer", "user": {...}}
POST /auth/refresh
Exchange a refresh token for a new access token. No authentication required in the request, but a valid refresh_token must be provided.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "<your-refresh-token>"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/refresh",
json={"refresh_token": "<your-refresh-token>"}
)
result = response.json()
token = result['access_token']
print(f"New Token: {token}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/refresh`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
refresh_token: "<your-refresh-token>"
})
});
const result = await response.json();
console.log(`New Token: ${result.access_token}`);Response: {"access_token": "<JWT>", "refresh_token": "<JWT>", "expires_in": 3600, "token_type": "Bearer", "user": {...}}
POST /auth/validate
Validate a token by passing it via the X-Auth-Token header (not Authorization: Bearer). Returns the User object if valid. No standard bearer authentication required; instead, the token is passed in a custom header.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/validate \
-H "X-Auth-Token: <your-token>"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/auth/validate",
headers={"X-Auth-Token": "<your-token>"}
)
user = response.json()
print(f"User ID: {user['id']}, Email: {user['email']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const response = await fetch(`${BASE}/auth/validate`, {
method: "POST",
headers: {
"X-Auth-Token": "<your-token>"
}
});
const user = await response.json();
console.log(`User ID: ${user.id}, Email: ${user.email}`);Response: {"id": "user-id", "email": "[email protected]", "first_name": "John", "last_name": "Doe", ...}
GET /auth/me
Retrieve the current authenticated user's profile. Requires Authorization: Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/auth/me \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
response = requests.get(
f"{BASE}/auth/me",
headers={"Authorization": f"Bearer {token}"}
)
user = response.json()
print(f"Current User: {user['email']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const response = await fetch(`${BASE}/auth/me`, {
headers: {
"Authorization": `Bearer ${token}`
}
});
const user = await response.json();
console.log(`Current User: ${user.email}`);Response: {"id": "user-id", "email": "[email protected]", "first_name": "John", "last_name": "Doe", ...}
POST /auth/api-keys
Create a new API key for programmatic access. The raw key is shown only once in the response. Requires Authorization: Bearer token.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/api-keys \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Integration Key",
"scopes": ["agents:read", "conversations:read"]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
response = requests.post(
f"{BASE}/auth/api-keys",
headers={"Authorization": f"Bearer {token}"},
json={
"name": "My Integration Key",
"scopes": ["agents:read", "conversations:read"]
}
)
result = response.json()
print(f"Raw Key (save this!): {result['key']}")
print(f"API Key ID: {result['api_key']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const response = await fetch(`${BASE}/auth/api-keys`, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "My Integration Key",
scopes: ["agents:read", "conversations:read"]
})
});
const result = await response.json();
console.log(`Raw Key (save this!): ${result.key}`);
console.log(`API Key ID: ${result.api_key}`);Response: {"api_key": "key-id", "key": "sk_live_...", ...}
GET /auth/api-keys
List all API keys created by the current user. Requires Authorization: Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/auth/api-keys \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
response = requests.get(
f"{BASE}/auth/api-keys",
headers={"Authorization": f"Bearer {token}"}
)
keys = response.json()
for key in keys:
print(f"Key: {key['api_key']}, Name: {key['name']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const response = await fetch(`${BASE}/auth/api-keys`, {
headers: {
"Authorization": `Bearer ${token}`
}
});
const keys = await response.json();
keys.forEach(key => {
console.log(`Key: ${key.api_key}, Name: ${key.name}`);
});Response: [{"api_key": "key-id", "name": "My Integration Key", ...}, ...]
POST /auth/workspaces
Create a new workspace. Workspaces are used to organize agents, conversations, and related resources for different projects or teams. Requires Authorization: Bearer token.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/workspaces \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
response = requests.post(
f"{BASE}/auth/workspaces",
headers={"Authorization": f"Bearer {token}"},
json={"name": "Customer Support"}
)
workspace = response.json()
print(f"Workspace ID: {workspace['id']}, Name: {workspace['name']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const response = await fetch(`${BASE}/auth/workspaces`, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Customer Support"
})
});
const workspace = await response.json();
console.log(`Workspace ID: ${workspace.id}, Name: ${workspace.name}`);Response: {"id": "workspace-id", "user_id": "user-id", "name": "Customer Support", "created_at": "2024-...", "updated_at": "2024-..."}
GET /auth/workspaces
List all workspaces for the current user. Requires Authorization: Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/auth/workspaces \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
response = requests.get(
f"{BASE}/auth/workspaces",
headers={"Authorization": f"Bearer {token}"}
)
workspaces = response.json()
for ws in workspaces:
print(f"Workspace: {ws['name']} (ID: {ws['id']})")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const response = await fetch(`${BASE}/auth/workspaces`, {
headers: {
"Authorization": `Bearer ${token}`
}
});
const workspaces = await response.json();
workspaces.forEach(ws => {
console.log(`Workspace: ${ws.name} (ID: ${ws.id})`);
});Response: [{"id": "workspace-id", "user_id": "user-id", "name": "Customer Support", ...}, ...]
GET /auth/workspaces/{id}
Retrieve details for a specific workspace by ID. Requires Authorization: Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
response = requests.get(
f"{BASE}/auth/workspaces/{workspace_id}",
headers={"Authorization": f"Bearer {token}"}
)
workspace = response.json()
print(f"Workspace: {workspace['name']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}`, {
headers: {
"Authorization": `Bearer ${token}`
}
});
const workspace = await response.json();
console.log(`Workspace: ${workspace.name}`);Response: {"id": "workspace-id", "user_id": "user-id", "name": "Customer Support", "created_at": "2024-...", "updated_at": "2024-..."}
PUT /auth/workspaces/{id}
Update a workspace's details. Requires Authorization: Bearer token. (Request body shape unverified.)
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Workspace Name"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
response = requests.put(
f"{BASE}/auth/workspaces/{workspace_id}",
headers={"Authorization": f"Bearer {token}"},
json={"name": "Updated Workspace Name"}
)
workspace = response.json()
print(f"Updated workspace: {workspace['name']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}`, {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Updated Workspace Name"
})
});
const workspace = await response.json();
console.log(`Updated workspace: ${workspace.name}`);Response: {"id": "workspace-id", "user_id": "user-id", "name": "Updated Workspace Name", ...}
DELETE /auth/workspaces/{id}
Delete a workspace. Requires Authorization: Bearer token. (Response body shape unverified.)
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
response = requests.delete(
f"{BASE}/auth/workspaces/{workspace_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(f"Status: {response.status_code}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}`, {
method: "DELETE",
headers: {
"Authorization": `Bearer ${token}`
}
});
console.log(`Status: ${response.status}`);Response: shape unverified
POST /auth/workspaces/{workspaceID}/memory
Create a workspace memory item (knowledge base entry). This stores information that agents in the workspace can reference. Requires Authorization: Bearer token. The title and content fields are required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id/memory \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Company Policies",
"content": "All support staff must follow company policy XYZ...",
"content_type": "text/plain",
"metadata": {"category": "policies"}
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
response = requests.post(
f"{BASE}/auth/workspaces/{workspace_id}/memory",
headers={"Authorization": f"Bearer {token}"},
json={
"title": "Company Policies",
"content": "All support staff must follow company policy XYZ...",
"content_type": "text/plain",
"metadata": {"category": "policies"}
}
)
memory = response.json()
print(f"Memory ID: {memory['id']}, Title: {memory['title']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}/memory`, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
title: "Company Policies",
content: "All support staff must follow company policy XYZ...",
content_type: "text/plain",
metadata: { category: "policies" }
})
});
const memory = await response.json();
console.log(`Memory ID: ${memory.id}, Title: ${memory.title}`);Response: {"id": "memory-id", "workspace_id": "workspace-id", "title": "Company Policies", "content": "...", "content_type": "text/plain", "metadata": {...}, "created_at": "2024-...", "updated_at": "2024-..."}
GET /auth/workspaces/{workspaceID}/memory
List all memory items in a workspace. Requires Authorization: Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id/memory \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
response = requests.get(
f"{BASE}/auth/workspaces/{workspace_id}/memory",
headers={"Authorization": f"Bearer {token}"}
)
memory_items = response.json()
for item in memory_items:
print(f"Memory: {item['title']} (ID: {item['id']})")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}/memory`, {
headers: {
"Authorization": `Bearer ${token}`
}
});
const memoryItems = await response.json();
memoryItems.forEach(item => {
console.log(`Memory: ${item.title} (ID: ${item.id})`);
});Response: [{"id": "memory-id", "workspace_id": "workspace-id", "title": "Company Policies", ...}, ...]
PUT /auth/workspaces/{workspaceID}/memory/{memoryID}
Update a memory item. All fields are optional. Requires Authorization: Bearer token.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id/memory/memory-id \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Company Policies",
"content": "Updated content here...",
"is_active": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
memory_id = "memory-id"
response = requests.put(
f"{BASE}/auth/workspaces/{workspace_id}/memory/{memory_id}",
headers={"Authorization": f"Bearer {token}"},
json={
"title": "Updated Company Policies",
"content": "Updated content here...",
"is_active": True
}
)
memory = response.json()
print(f"Updated memory: {memory['title']}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const memoryId = "memory-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}/memory/${memoryId}`, {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
title: "Updated Company Policies",
content: "Updated content here...",
is_active: true
})
});
const memory = await response.json();
console.log(`Updated memory: ${memory.title}`);Response: {"id": "memory-id", "workspace_id": "workspace-id", "title": "Updated Company Policies", ...}
DELETE /auth/workspaces/{workspaceID}/memory/{memoryID}
Delete a memory item. Requires Authorization: Bearer token. (Response body shape unverified.)
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/auth/workspaces/workspace-id/memory/memory-id \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "<your-access-token>"
workspace_id = "workspace-id"
memory_id = "memory-id"
response = requests.delete(
f"{BASE}/auth/workspaces/{workspace_id}/memory/{memory_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(f"Status: {response.status_code}")JAVASCRIPT
const BASE = "https://ultravoice.us.inc/api/v1";
const token = "<your-access-token>";
const workspaceId = "workspace-id";
const memoryId = "memory-id";
const response = await fetch(`${BASE}/auth/workspaces/${workspaceId}/memory/${memoryId}`, {
method: "DELETE",
headers: {
"Authorization": `Bearer ${token}`
}
});
console.log(`Status: ${response.status}`);Response: shape unverified
Agents
Manage AI agents within a workspace. Create, configure, and deploy conversational agents with voice capabilities, knowledge bases, and Twilio telephony integration. All endpoints require Bearer token authentication.
POST /agents
Create a new agent. Requires Bearer token. Returns the created agent object.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "ws_123",
"name": "Customer Support Agent",
"description": "Handles customer inquiries",
"system_prompt": "You are a helpful customer support agent.",
"welcome_message": "Hello, how can I help you today?",
"language": "en",
"max_turns": 20,
"connection_type": "voice",
"interrupt_enabled": true,
"vad_threshold": 0.5,
"silence_timeout_ms": 2000
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
payload = {
"workspace_id": "ws_123",
"name": "Customer Support Agent",
"description": "Handles customer inquiries",
"system_prompt": "You are a helpful customer support agent.",
"welcome_message": "Hello, how can I help you today?",
"language": "en",
"max_turns": 20,
"connection_type": "voice",
"interrupt_enabled": True,
"vad_threshold": 0.5,
"silence_timeout_ms": 2000
}
response = requests.post(
f"{BASE}/agents",
json=payload,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const payload = {
workspace_id: 'ws_123',
name: 'Customer Support Agent',
description: 'Handles customer inquiries',
system_prompt: 'You are a helpful customer support agent.',
welcome_message: 'Hello, how can I help you today?',
language: 'en',
max_turns: 20,
connection_type: 'voice',
interrupt_enabled: true,
vad_threshold: 0.5,
silence_timeout_ms: 2000
};
fetch(`${BASE}/agents`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response: Agent object with fields id, workspace_id, user_id, name, description, system_prompt, welcome_message, language, max_turns, interrupt_enabled, vad_threshold, silence_timeout_ms, connection_type, is_active, allow_human_transfer, mode, metadata, created_at, updated_at.
GET /agents
List all agents in a workspace. Requires Bearer token. Supports pagination with workspace_id filter.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/agents?workspace_id=ws_123&limit=10&offset=0" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
params = {
"workspace_id": "ws_123",
"limit": 10,
"offset": 0
}
response = requests.get(
f"{BASE}/agents",
params=params,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const params = new URLSearchParams({
workspace_id: 'ws_123',
limit: 10,
offset: 0
});
fetch(`${BASE}/agents?${params}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: Array of Agent objects with pagination metadata (page, per_page, total, total_pages).
GET /agents/lookup/phone
Look up an agent by phone number. Requires Bearer token. Returns agent details and telephony configuration.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/agents/lookup/phone?phone_number=%2B14155552671" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
params = {"phone_number": "+14155552671"}
response = requests.get(
f"{BASE}/agents/lookup/phone",
params=params,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const params = new URLSearchParams({
phone_number: '+14155552671'
});
fetch(`${BASE}/agents/lookup/phone?${params}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: Object containing agent (Agent object) and telephony (AgentTelephony configuration).
GET /agents/{id}
Get detailed agent information. Requires Bearer token. Returns agent, providers, telephony config, and knowledge bases.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent_xyz \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
response = requests.get(
f"{BASE}/agents/{agent_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
fetch(`${BASE}/agents/${agentId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: AgentDetailResponse containing agent object, providers array, optional telephony config, and optional knowledge_bases array.
PUT /agents/{id}
Update an agent. Requires Bearer token. All fields are optional.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent_xyz \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Agent Name",
"system_prompt": "Updated system prompt",
"max_turns": 30,
"is_active": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
payload = {
"name": "Updated Agent Name",
"system_prompt": "Updated system prompt",
"max_turns": 30,
"is_active": True
}
response = requests.put(
f"{BASE}/agents/{agent_id}",
json=payload,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
const payload = {
name: 'Updated Agent Name',
system_prompt: 'Updated system prompt',
max_turns: 30,
is_active: true
};
fetch(`${BASE}/agents/${agentId}`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response: Updated Agent object.
DELETE /agents/{id}
Delete an agent. Requires Bearer token.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/agent_xyz \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
response = requests.delete(
f"{BASE}/agents/{agent_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
fetch(`${BASE}/agents/${agentId}`, {
method: 'DELETE',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: Confirmation message {message: "deleted"}.
Providers
Configure LLM and voice providers for an agent.
POST /agents/{id}/providers
Set or create a provider configuration for an agent. Requires Bearer token. Supports multiple provider types (LLM, TTS, ASR, etc.).
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent_xyz/providers \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"provider_type": "llm",
"provider_name": "openai",
"api_key": "sk_...",
"model_name": "gpt-4",
"base_url": "https://api.openai.com/v1"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
payload = {
"provider_type": "llm",
"provider_name": "openai",
"api_key": "sk_...",
"model_name": "gpt-4",
"base_url": "https://api.openai.com/v1"
}
response = requests.post(
f"{BASE}/agents/{agent_id}/providers",
json=payload,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
const payload = {
provider_type: 'llm',
provider_name: 'openai',
api_key: 'sk_...',
model_name: 'gpt-4',
base_url: 'https://api.openai.com/v1'
};
fetch(`${BASE}/agents/${agentId}/providers`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response: AgentProvider object. API key is masked unless request is from an internal service.
GET /agents/{id}/providers
List all providers configured for an agent. Requires Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent_xyz/providers \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
response = requests.get(
f"{BASE}/agents/{agent_id}/providers",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
fetch(`${BASE}/agents/${agentId}/providers`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: Array of AgentProvider objects.
DELETE /agents/{id}/providers/{type}
Delete a provider configuration from an agent. Requires Bearer token.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/agent_xyz/providers/llm \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
provider_type = "llm"
response = requests.delete(
f"{BASE}/agents/{agent_id}/providers/{provider_type}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
const providerType = 'llm';
fetch(`${BASE}/agents/${agentId}/providers/${providerType}`, {
method: 'DELETE',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: Confirmation message {message: "deleted"}.
Telephony
Configure Twilio phone integration for agent inbound/outbound calls.
PUT /agents/{id}/telephony
Set Twilio telephony configuration for an agent. Requires Bearer token. Enables phone call support via Twilio.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent_xyz/telephony \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"twilio_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"twilio_auth_token": "your_auth_token",
"twilio_phone_number": "+14155552671",
"webhook_url": "https://yourdomain.com/webhook",
"call_direction": "inbound",
"human_transfer_number": "+15551234567"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
payload = {
"twilio_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"twilio_auth_token": "your_auth_token",
"twilio_phone_number": "+14155552671",
"webhook_url": "https://yourdomain.com/webhook",
"call_direction": "inbound",
"human_transfer_number": "+15551234567"
}
response = requests.put(
f"{BASE}/agents/{agent_id}/telephony",
json=payload,
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
const payload = {
twilio_account_sid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
twilio_auth_token: 'your_auth_token',
twilio_phone_number: '+14155552671',
webhook_url: 'https://yourdomain.com/webhook',
call_direction: 'inbound',
human_transfer_number: '+15551234567'
};
fetch(`${BASE}/agents/${agentId}/telephony`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response: AgentTelephony object containing telephony configuration. Twilio auth token is masked unless request is from an internal service.
GET /agents/{id}/telephony
Retrieve the Twilio telephony configuration for an agent. Requires Bearer token.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent_xyz/telephony \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_TOKEN"
agent_id = "agent_xyz"
response = requests.get(
f"{BASE}/agents/{agent_id}/telephony",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_TOKEN';
const BASE = 'https://ultravoice.us.inc/api/v1';
const agentId = 'agent_xyz';
fetch(`${BASE}/agents/${agentId}/telephony`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response: AgentTelephony object with Twilio configuration details.
Agent Tools, Knowledge & Flow
Manage AI agent tools, knowledge bases, handbook snippets, flow configurations, versioning, and test simulations. These endpoints enable building and refining agent behavior through structured tools, knowledge attachments, prompt engineering, version control, and automated testing.
Tools
Create and manage tools that agents can invoke. Tools define external API integrations, function schemas, and execution parameters.
POST /agents/{id}/tools
Create a tool for an agent. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/tools \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "weather_lookup",
"description": "Get current weather for a location",
"function_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"endpoint_url": "https://api.weather.example.com/current",
"http_method": "GET",
"auth_type": "api_key",
"auth_token": "weather_api_key_123",
"timeout_ms": 5000,
"retry_count": 2
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/tools",
headers=headers,
json={
"name": "weather_lookup",
"description": "Get current weather for a location",
"function_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"]
},
"endpoint_url": "https://api.weather.example.com/current",
"http_method": "GET",
"auth_type": "api_key",
"auth_token": "weather_api_key_123",
"timeout_ms": 5000,
"retry_count": 2
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/tools",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "weather_lookup",
description: "Get current weather for a location",
function_schema: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"]
},
endpoint_url: "https://api.weather.example.com/current",
http_method: "GET",
auth_type: "api_key",
auth_token: "weather_api_key_123",
timeout_ms: 5000,
retry_count: 2
})
}
);
const tool = await response.json();
console.log(tool);Response: Tool object with `id`, `agent_id`, `name`, `description`, `function_schema`, `endpoint_url`, `http_method`, `headers`, `auth_type`, `request_body`, `response_path`, `timeout_ms`, `retry_count`, `is_active`, `connector_binding`, `created_at`, `updated_at`.
GET /agents/{id}/tools
List all tools for an agent. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/tools \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/tools", headers=headers)
tools = response.json()
print(tools)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/tools",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const tools = await response.json();
console.log(tools);Response: Array of Tool objects.
GET /agents/{id}/tools/{toolID}
Get a single tool by ID. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/tools/tool456", headers=headers)
tool = response.json()
print(tool)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const tool = await response.json();
console.log(tool);Response: Tool object.
PUT /agents/{id}/tools/{toolID}
Update a tool. All fields are optional pointers. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description": "Updated weather lookup tool",
"timeout_ms": 10000,
"is_active": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/tools/tool456",
headers=headers,
json={
"description": "Updated weather lookup tool",
"timeout_ms": 10000,
"is_active": True
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
description: "Updated weather lookup tool",
timeout_ms: 10000,
is_active: true
})
}
);
const tool = await response.json();
console.log(tool);Response: Updated Tool object.
DELETE /agents/{id}/tools/{toolID}
Delete a tool. Requires `bearer` authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.delete(f"{BASE}/agents/agent123/tools/tool456", headers=headers)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/tools/tool456",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const result = await response.json();
console.log(result);Response: `{message}` confirmation.
Knowledge Bases
Attach workspace knowledge bases to agents. Knowledge bases (created at `/auth/workspaces/{workspaceID}/memory`) provide context and reference material for agent reasoning.
POST /agents/{id}/knowledge-bases
Attach a knowledge base to an agent. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"knowledge_base_id": "kb789",
"mode": "always"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/knowledge-bases",
headers=headers,
json={
"knowledge_base_id": "kb789",
"mode": "always"
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
knowledge_base_id: "kb789",
mode: "always"
})
}
);
const kb = await response.json();
console.log(kb);Response: AgentKnowledgeBase object with `id`, `agent_id`, `knowledge_base_id`, `mode`, `is_active`, `created_at`, `updated_at`.
GET /agents/{id}/knowledge-bases
List all knowledge bases attached to an agent. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/knowledge-bases", headers=headers)
kbs = response.json()
print(kbs)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const kbs = await response.json();
console.log(kbs);Response: Array of AgentKnowledgeBase objects.
PUT /agents/{id}/knowledge-bases/{kbID}
Update a knowledge base binding (mode and/or active status). Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases/kb789 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mode": "on_demand",
"is_active": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/knowledge-bases/kb789",
headers=headers,
json={
"mode": "on_demand",
"is_active": True
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases/kb789",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
mode: "on_demand",
is_active: true
})
}
);
const kb = await response.json();
console.log(kb);Response: Updated AgentKnowledgeBase object.
DELETE /agents/{id}/knowledge-bases/{kbID}
Detach a knowledge base from an agent. Requires `bearer` authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases/kb789 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.delete(
f"{BASE}/agents/agent123/knowledge-bases/kb789",
headers=headers
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/knowledge-bases/kb789",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const result = await response.json();
console.log(result);Response: `{message}` confirmation.
Handbook / Prompt Snippets
Manage reusable prompt snippets at the workspace level and compose them into agent handbooks for structured prompt engineering.
POST /agents/snippets
Create a prompt snippet in the workspace. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/snippets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "ws123",
"title": "Customer Service Tone",
"body": "Always be polite, empathetic, and professional. Acknowledge customer concerns and offer solutions.",
"category": "tone"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/snippets",
headers=headers,
json={
"workspace_id": "ws123",
"title": "Customer Service Tone",
"body": "Always be polite, empathetic, and professional. Acknowledge customer concerns and offer solutions.",
"category": "tone"
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/snippets",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
workspace_id: "ws123",
title: "Customer Service Tone",
body: "Always be polite, empathetic, and professional. Acknowledge customer concerns and offer solutions.",
category: "tone"
})
}
);
const snippet = await response.json();
console.log(snippet);Response: PromptSnippet object with `id`, `workspace_id`, `title`, `body`, `category`, `is_seed`, `created_at`, `updated_at`.
GET /agents/snippets
List all prompt snippets in a workspace. Query parameter `workspace_id` is required. Requires `bearer` authentication.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/agents/snippets?workspace_id=ws123' \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
f"{BASE}/agents/snippets",
headers=headers,
params={"workspace_id": "ws123"}
)
snippets = response.json()
print(snippets)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/snippets?workspace_id=ws123",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const snippets = await response.json();
console.log(snippets);Response: Array of PromptSnippet objects.
GET /agents/snippets/{id}
Get a single snippet by ID. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/snippets/snip456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/snippets/snip456", headers=headers)
snippet = response.json()
print(snippet)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/snippets/snip456",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const snippet = await response.json();
console.log(snippet);Response: PromptSnippet object.
PUT /agents/snippets/{id}
Update a snippet. Seed snippets are read-only. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/snippets/snip456 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Customer Service Tone",
"body": "Be warm, patient, and solution-focused.",
"category": "tone"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/snippets/snip456",
headers=headers,
json={
"title": "Updated Customer Service Tone",
"body": "Be warm, patient, and solution-focused.",
"category": "tone"
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/snippets/snip456",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
title: "Updated Customer Service Tone",
body: "Be warm, patient, and solution-focused.",
category: "tone"
})
}
);
const snippet = await response.json();
console.log(snippet);Response: Updated PromptSnippet object.
DELETE /agents/snippets/{id}
Delete a snippet. Seed snippets are read-only. Requires `bearer` authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/snippets/snip456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.delete(f"{BASE}/agents/snippets/snip456", headers=headers)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/snippets/snip456",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const result = await response.json();
console.log(result);Response: `{message}` confirmation.
GET /agents/{id}/handbook
Get the resolved handbook for an agent, listing all attached prompt snippets. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/handbook \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/handbook", headers=headers)
handbook = response.json()
print(handbook)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/handbook",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const handbook = await response.json();
console.log(handbook);Response: AgentHandbookResponse with `agent_id`, `snippets[]`, `missing_ids[]`.
PUT /agents/{id}/handbook
Set the ordered list of snippet IDs for an agent's handbook. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/handbook \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"snippet_ids": ["snip456", "snip789", "snip101"]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/handbook",
headers=headers,
json={
"snippet_ids": ["snip456", "snip789", "snip101"]
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/handbook",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
snippet_ids: ["snip456", "snip789", "snip101"]
})
}
);
const handbook = await response.json();
console.log(handbook);Response: Updated AgentHandbookResponse.
Versioning
Track and manage agent configuration versions. Publish drafts, view historical snapshots, and rollback to prior versions.
GET /agents/{id}/versions
List all versions of an agent. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/versions \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/versions", headers=headers)
versions = response.json()
print(versions)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/versions",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const versions = await response.json();
console.log(versions);Response: VersionListResponse with `agent_id`, `live_version`, `draft_dirty`, `versions[]`.
GET /agents/{id}/versions/diff
Get a diff between two agent versions. Query parameters `from` and `to` are optional (values: int for version number, `draft` for draft version, or unspecified for latest). Requires `bearer` authentication.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/agents/agent123/versions/diff?from=1&to=2' \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
f"{BASE}/agents/agent123/versions/diff",
headers=headers,
params={"from": 1, "to": 2}
)
diff = response.json()
print(diff)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/versions/diff?from=1&to=2",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const diff = await response.json();
console.log(diff);Response: VersionDiff with `from`, `to`, `changes[]`, `summary`.
GET /agents/{id}/versions/{version}
Get a specific version snapshot. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/versions/2 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/versions/2", headers=headers)
version = response.json()
print(version)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/versions/2",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const version = await response.json();
console.log(version);Response: AgentVersion with `id`, `agent_id`, `version_number`, `status`, `snapshot`, `published_at`, `published_by`, `notes`, `created_at`.
POST /agents/{id}/versions/publish
Publish the draft version as a new live version. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/versions/publish \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notes": "Improved system prompt for better accuracy"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/versions/publish",
headers=headers,
json={
"notes": "Improved system prompt for better accuracy"
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/versions/publish",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
notes: "Improved system prompt for better accuracy"
})
}
);
const result = await response.json();
console.log(result);Response: PublishResponse with `version_number`, `published_at`, `message`.
POST /agents/{id}/versions/{version}/rollback
Rollback to a prior published version. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/versions/1/rollback \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/versions/1/rollback",
headers=headers
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/versions/1/rollback",
{
method: "POST",
headers: { "Authorization": `Bearer ${token}` }
}
);
const result = await response.json();
console.log(result);Response: PublishResponse with `version_number`, `published_at`, `message`.
Flow Builder
Design agent conversations as directed graphs. Define nodes (decision branches, function calls, user input), edges, and flow variables to orchestrate complex multi-turn interactions.
GET /agents/{id}/flow
Get the conversation flow graph for an agent. Returns an empty flow if none exists. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/flow \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/flow", headers=headers)
flow = response.json()
print(flow)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/flow",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const flow = await response.json();
console.log(flow);Response: ConversationFlow with `id`, `agent_id`, `version`, `graph{nodes[], edges[], start_node_id}`, `variables[]`, `is_valid`, `validation_errors[]`, `created_at`, `updated_at`.
PUT /agents/{id}/flow
Save a conversation flow graph for an agent. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/flow \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"graph": {
"nodes": [
{"id": "n1", "type": "start", "label": "Welcome"},
{"id": "n2", "type": "prompt", "label": "Get Issue"}
],
"edges": [
{"from": "n1", "to": "n2"}
],
"start_node_id": "n1"
},
"variables": [{"name": "issue_type", "type": "string"}]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/flow",
headers=headers,
json={
"graph": {
"nodes": [
{"id": "n1", "type": "start", "label": "Welcome"},
{"id": "n2", "type": "prompt", "label": "Get Issue"}
],
"edges": [
{"from": "n1", "to": "n2"}
],
"start_node_id": "n1"
},
"variables": [{"name": "issue_type", "type": "string"}]
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/flow",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
graph: {
nodes: [
{ id: "n1", type: "start", label: "Welcome" },
{ id: "n2", type: "prompt", label: "Get Issue" }
],
edges: [
{ from: "n1", to: "n2" }
],
start_node_id: "n1"
},
variables: [{ name: "issue_type", type: "string" }]
})
}
);
const flow = await response.json();
console.log(flow);Response: ConversationFlow object.
POST /agents/{id}/flow/validate
Validate a flow graph without saving. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/flow/validate \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"graph": {
"nodes": [{"id": "n1", "type": "start"}],
"edges": [],
"start_node_id": "n1"
}
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/flow/validate",
headers=headers,
json={
"graph": {
"nodes": [{"id": "n1", "type": "start"}],
"edges": [],
"start_node_id": "n1"
}
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/flow/validate",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
graph: {
nodes: [{ id: "n1", type: "start" }],
edges: [],
start_node_id: "n1"
}
})
}
);
const result = await response.json();
console.log(result);Response: `{is_valid(bool), errors[]}`.
PUT /agents/{id}/mode
Set agent operation mode. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/mode \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mode": "flow"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/mode",
headers=headers,
json={"mode": "flow"}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/mode",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ mode: "flow" })
}
);
const result = await response.json();
console.log(result);Supported modes: `single_prompt`, `flow`. Response: `{mode}`.
GET /agents/{id}/mode
Get the current agent operation mode. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/mode \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/mode", headers=headers)
mode = response.json()
print(mode)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/mode",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const mode = await response.json();
console.log(mode);Response: `{mode}`.
Simulation Testing
Create and run automated test cases against agents. Define personas, conversation goals, and assertions; monitor test run progress and review results.
GET /agents/{id}/test-cases
List all test cases for an agent. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/agent123/test-cases \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/agent123/test-cases", headers=headers)
cases = response.json()
print(cases)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-cases",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const cases = await response.json();
console.log(cases);Response: Array of TestCase objects with `id`, `agent_id`, `name`, `persona`, `goal`, `assertions[]`, `max_turns`, `tags`, `created_at`, `updated_at`.
POST /agents/{id}/test-cases
Create a test case for an agent. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/test-cases \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Happy Path",
"persona": "Frustrated customer",
"goal": "Get order refund approved",
"assertions": ["agent_resolved_issue", "customer_satisfied"],
"max_turns": 10,
"tags": ["refund", "critical"]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/test-cases",
headers=headers,
json={
"name": "Happy Path",
"persona": "Frustrated customer",
"goal": "Get order refund approved",
"assertions": ["agent_resolved_issue", "customer_satisfied"],
"max_turns": 10,
"tags": ["refund", "critical"]
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-cases",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Happy Path",
persona: "Frustrated customer",
goal: "Get order refund approved",
assertions: ["agent_resolved_issue", "customer_satisfied"],
max_turns: 10,
tags: ["refund", "critical"]
})
}
);
const testCase = await response.json();
console.log(testCase);Response: TestCase object.
PUT /agents/{id}/test-cases/{tcId}
Update a test case. All fields are optional. Requires `bearer` authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/agents/agent123/test-cases/tc456 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"goal": "Get order refund approved within 5 minutes",
"max_turns": 15
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.put(
f"{BASE}/agents/agent123/test-cases/tc456",
headers=headers,
json={
"goal": "Get order refund approved within 5 minutes",
"max_turns": 15
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-cases/tc456",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
goal: "Get order refund approved within 5 minutes",
max_turns: 15
})
}
);
const testCase = await response.json();
console.log(testCase);Response: Updated TestCase object.
DELETE /agents/{id}/test-cases/{tcId}
Delete a test case. Requires `bearer` authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/agent123/test-cases/tc456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.delete(
f"{BASE}/agents/agent123/test-cases/tc456",
headers=headers
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-cases/tc456",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const result = await response.json();
console.log(result);Response: `{status:"deleted"}`.
POST /agents/{id}/test-runs
Start a test run against an agent. If `case_ids` is omitted, all test cases are executed. Requires `bearer` authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/agent123/test-runs \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_version": 2,
"case_ids": ["tc456", "tc789"]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
f"{BASE}/agents/agent123/test-runs",
headers=headers,
json={
"agent_version": 2,
"case_ids": ["tc456", "tc789"]
}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-runs",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_version: 2,
case_ids: ["tc456", "tc789"]
})
}
);
const testRun = await response.json();
console.log(testRun);Response: TestRun object with `id`, `agent_id`, `agent_version`, `status`, `total`, `passed`, `failed`, `errored`, `triggered_by`, `started_at`, `last_heartbeat`.
GET /agents/{id}/test-runs
List test runs for an agent. Query parameters: `limit?` (default 20), `offset?`. Requires `bearer` authentication.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/agents/agent123/test-runs?limit=10&offset=0' \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
f"{BASE}/agents/agent123/test-runs",
headers=headers,
params={"limit": 10, "offset": 0}
)
print(response.json())JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/agent123/test-runs?limit=10&offset=0",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const testRuns = await response.json();
console.log(testRuns);Response: Array of TestRun objects + metadata.
GET /agents/test-runs/{runId}
Get a specific test run. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/test-runs/run789 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/test-runs/run789", headers=headers)
testRun = response.json()
print(testRun)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/test-runs/run789",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const testRun = await response.json();
console.log(testRun);Response: TestRun object.
GET /agents/test-runs/{runId}/results
Get all test results from a test run. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/test-runs/run789/results \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(f"{BASE}/agents/test-runs/run789/results", headers=headers)
results = response.json()
print(results)JAVASCRIPT
const token = "$TOKEN";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/agents/test-runs/run789/results",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const results = await response.json();
console.log(results);Response: Array of TestResult objects with `id`, `test_run_id`, `test_case_id`, `test_case_name`, `status`, `transcript[]`, `assertion_results[]`, `turns_taken`, `duration_ms`, `tokens_used`, `retry_count`, `error_message`, `created_at`.
GET /agents/test-runs/{runId}/stream
Server-Sent Events stream for live test run progress. Polls every 2 seconds and closes when the run completes. Requires `bearer` authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/agents/test-runs/run789/stream \
-H "Authorization: Bearer $TOKEN" \
-NPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "$TOKEN"
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
f"{BASE}/agents/test-runs/run789/stream",
headers=headers,
stream=True
)
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))JAVASCRIPT
const token = "$TOKEN";
const eventSource = new EventSource(
`https://ultravoice.us.inc/api/v1/agents/test-runs/run789/stream`,
{ headers: { "Authorization": `Bearer ${token}` } }
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log("Test run progress:", data.run);
console.log("Results so far:", data.results);
};
eventSource.onerror = () => {
eventSource.close();
};Response (SSE): Server-Sent Events with `data: {run, results}` payloads. Stream closes on run completion (status: completed/failed/cancelled).
Connectors / Integrations (Agent Tool Bindings)
Use connectors to bind third-party API integrations to agents as callable tools. Connectors abstract OAuth authentication and action invocation.
GET /connectors/connectors
List the catalog of available connectors. No authentication required.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/connectors/connectorsPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(f"{BASE}/connectors/connectors")
connectors = response.json()
print(connectors)JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/connectors",
{ method: "GET" }
);
const connectors = await response.json();
console.log(connectors);Response: `{data:[{id, name, description, icon_url, oauth_scopes, actions, is_active}]}`.
GET /connectors/workspace/{workspace_id}/connections
List OAuth connections for a workspace. No authentication required.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connectionsPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(f"{BASE}/connectors/workspace/ws123/connections")
connections = response.json()
print(connections)JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connections",
{ method: "GET" }
);
const connections = await response.json();
console.log(connections);Response: `{data:[{id, workspace_id, connector_id, account_label, token_expires_at, is_active, created_at, connector_name, icon_url, description, actions}]}`.
POST /connectors/workspace/{workspace_id}/connect/{connector_id}
Initiate OAuth flow for a connector. Returns an authorization URL. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connect/google_calendarPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/connectors/workspace/ws123/connect/google_calendar"
)
auth_response = response.json()
print(f"Auth URL: {auth_response['auth_url']}")JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connect/google_calendar",
{ method: "POST" }
);
const authResponse = await response.json();
console.log(`Auth URL: ${authResponse.auth_url}`);Response: `{auth_url}`.
GET /connectors/oauth/callback
OAuth redirect handler (called by third-party provider). Query parameters: `code`, `state`, `error`. No authentication required.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/connectors/oauth/callback?code=AUTH_CODE&state=STATE_VALUE'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(
f"{BASE}/connectors/oauth/callback",
params={"code": "AUTH_CODE", "state": "STATE_VALUE"}
)
print(f"Redirect: {response.headers.get('Location')}")JAVASCRIPT
// Typically handled by the browser as a redirect
// In a server context:
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/oauth/callback?code=AUTH_CODE&state=STATE_VALUE"
);
const location = response.headers.get("location");
console.log(`Redirects to: ${location}`);Response: 302 Redirect to frontend.
DELETE /connectors/workspace/{workspace_id}/connections/{connection_id}
Disconnect (soft delete) a connector connection. No authentication required.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connections/conn456PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.delete(
f"{BASE}/connectors/workspace/ws123/connections/conn456"
)
print(response.json())JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/workspace/ws123/connections/conn456",
{ method: "DELETE" }
);
const result = await response.json();
console.log(result);Response: `{message:"disconnected"}`.
GET /connectors/agents/{agent_id}/connectors
List enabled connectors for an agent (tokens stripped for security). No authentication required.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectorsPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(f"{BASE}/connectors/agents/agent123/connectors")
connectors = response.json()
print(connectors)JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectors",
{ method: "GET" }
);
const connectors = await response.json();
console.log(connectors);Response: `{data:[...]}`.
POST /connectors/agents/{agent_id}/connectors
Enable a connector connection for an agent. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectors \
-H "Content-Type: application/json" \
-d '{
"connection_id": "conn456"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/connectors/agents/agent123/connectors",
json={"connection_id": "conn456"}
)
print(response.json())JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectors",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ connection_id: "conn456" })
}
);
const result = await response.json();
console.log(result);Response: `{message:"enabled"}`.
DELETE /connectors/agents/{agent_id}/connectors/{connection_id}
Disable a connector for an agent. No authentication required.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectors/conn456PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.delete(
f"{BASE}/connectors/agents/agent123/connectors/conn456"
)
print(response.json())JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/agents/agent123/connectors/conn456",
{ method: "DELETE" }
);
const result = await response.json();
console.log(result);Response: `{message:"disabled"}`.
POST /connectors/execute/{connection_id}/{action}
Execute a connector action (e.g. `check_availability`, `book_appointment`, `cancel_appointment` for Google Calendar). Request body is action-specific JSON. No authentication required.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/connectors/execute/conn456/book_appointment \
-H "Content-Type: application/json" \
-d '{
"title": "Customer Call",
"start_time": "2024-06-15T14:00:00Z",
"duration_minutes": 30
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.post(
f"{BASE}/connectors/execute/conn456/book_appointment",
json={
"title": "Customer Call",
"start_time": "2024-06-15T14:00:00Z",
"duration_minutes": 30
}
)
print(response.json())JAVASCRIPT
const response = await fetch(
"https://ultravoice.us.inc/api/v1/connectors/execute/conn456/book_appointment",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
title: "Customer Call",
start_time: "2024-06-15T14:00:00Z",
duration_minutes: 30
})
}
);
const result = await response.json();
console.log(result);Response: `{data: {...}}` (action-specific).
ℹ️
Connector endpoints have no authentication middleware at the application level. Network-level security or edge protection should be verified before exposing these endpoints to the public internet.
Providers Registry
Manage available ASR, LLM, and TTS provider definitions and user-specific provider configurations. The providers registry catalog lists all supported integrations, while user configs allow agents to override default settings per provider.
POST /providers
Create a provider definition in the catalog (requires bearer token).
BASH
curl -X POST https://ultravoice.us.inc/api/v1/providers \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "OpenAI",
"provider_type": "llm",
"description": "OpenAI GPT models",
"base_url": "https://api.openai.com/v1",
"auth_type": "api_key",
"default_config": {"temperature": 0.7},
"supported_models": ["gpt-4", "gpt-3.5-turbo"],
"supported_languages": ["en", "es", "fr"]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
response = requests.post(
f"{BASE}/providers",
headers={"Authorization": f"Bearer {token}"},
json={
"name": "OpenAI",
"provider_type": "llm",
"description": "OpenAI GPT models",
"base_url": "https://api.openai.com/v1",
"auth_type": "api_key",
"default_config": {"temperature": 0.7},
"supported_models": ["gpt-4", "gpt-3.5-turbo"],
"supported_languages": ["en", "es", "fr"]
}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const response = await fetch("https://ultravoice.us.inc/api/v1/providers", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "OpenAI",
provider_type: "llm",
description: "OpenAI GPT models",
base_url: "https://api.openai.com/v1",
auth_type: "api_key",
default_config: { temperature: 0.7 },
supported_models: ["gpt-4", "gpt-3.5-turbo"],
supported_languages: ["en", "es", "fr"]
})
});
const data = await response.json();
console.log(data);Response: `Provider {id, name, provider_type, description, base_url, auth_type, is_active, default_config, supported_models, supported_languages, created_at, updated_at}`
GET /providers
List all provider definitions in the catalog (requires bearer token).
BASH
curl -X GET https://ultravoice.us.inc/api/v1/providers \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
response = requests.get(
f"{BASE}/providers",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const response = await fetch("https://ultravoice.us.inc/api/v1/providers", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
});
const data = await response.json();
console.log(data);Response: `[]{id, name, provider_type, description, base_url, auth_type, is_active, default_config, supported_models, supported_languages, created_at, updated_at}`
GET /providers/{id}
Retrieve a specific provider definition (requires bearer token).
BASH
curl -X GET https://ultravoice.us.inc/api/v1/providers/provider-123 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
provider_id = "provider-123"
response = requests.get(
f"{BASE}/providers/{provider_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const providerId = "provider-123";
const response = await fetch(`https://ultravoice.us.inc/api/v1/providers/${providerId}`, {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
});
const data = await response.json();
console.log(data);Response: `Provider {id, name, provider_type, description, base_url, auth_type, is_active, default_config, supported_models, supported_languages, created_at, updated_at}`
POST /providers/user-config
Set or create a user/agent-specific provider configuration (requires bearer token).
BASH
curl -X POST https://ultravoice.us.inc/api/v1/providers/user-config \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent-456",
"provider_id": "provider-123",
"provider_type": "llm",
"api_key": "sk-...",
"model_name": "gpt-4",
"config": {"temperature": 0.9},
"is_default": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
response = requests.post(
f"{BASE}/providers/user-config",
headers={"Authorization": f"Bearer {token}"},
json={
"agent_id": "agent-456",
"provider_id": "provider-123",
"provider_type": "llm",
"api_key": "sk-...",
"model_name": "gpt-4",
"config": {"temperature": 0.9},
"is_default": True
}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const response = await fetch("https://ultravoice.us.inc/api/v1/providers/user-config", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_id: "agent-456",
provider_id: "provider-123",
provider_type: "llm",
api_key: "sk-...",
model_name: "gpt-4",
config: { temperature: 0.9 },
is_default: true
})
});
const data = await response.json();
console.log(data);Response: `UserProviderConfig` (api_key not serialized in response)
GET /providers/user-config
List all user/agent-specific provider configurations (requires bearer token).
BASH
curl -X GET https://ultravoice.us.inc/api/v1/providers/user-config \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
response = requests.get(
f"{BASE}/providers/user-config",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const response = await fetch("https://ultravoice.us.inc/api/v1/providers/user-config", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
});
const data = await response.json();
console.log(data);Response: `[]UserProviderConfig`
GET /providers/resolve
Resolve the effective provider configuration for an agent or workspace (requires bearer token). (shape unverified)
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/providers/resolve?agent_id=agent-456&provider_type=llm" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_bearer_token"
response = requests.get(
f"{BASE}/providers/resolve",
headers={"Authorization": f"Bearer {token}"},
params={"agent_id": "agent-456", "provider_type": "llm"}
)
print(response.json())JAVASCRIPT
const token = "your_bearer_token";
const params = new URLSearchParams({
agent_id: "agent-456",
provider_type: "llm"
});
const response = await fetch(`https://ultravoice.us.inc/api/v1/providers/resolve?${params}`, {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
});
const data = await response.json();
console.log(data);Response: Resolved provider configuration (query parameters and exact response shape not yet confirmed — verify in handler before using)
ℹ️
Health check endpoints are available at GET /providers/health, /providers/healthz, /providers/ready, and /providers/live (no auth required).
Sessions & WebSocket
The Sessions API provides endpoints for managing real-time session signaling and voice pipeline coordination. WebSocket connections enable bidirectional streaming of audio and control messages between clients and the UltraVoice platform.
GET /sessions/ws
WebSocket connection for session signaling. No authentication required. Initiates a WebSocket upgrade for real-time session management.
Example: Connect to Sessions WebSocket
JAVASCRIPT
const ws = new WebSocket('wss://ultravoice.us.inc/api/v1/sessions/ws');
ws.onopen = () => {
console.log('Connected to session WebSocket');
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
console.log('Received:', message);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
ws.onclose = () => {
console.log('Disconnected from session WebSocket');
};GET /sessions/active
List all active sessions. Requires Bearer token authentication.
Example: List Active Sessions (curl)
BASH
curl -X GET https://ultravoice.us.inc/api/v1/sessions/active \
-H "Authorization: Bearer $TOKEN"Example: List Active Sessions (Python)
PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
token = 'your_jwt_token'
response = requests.get(
f'{BASE}/sessions/active',
headers={'Authorization': f'Bearer {token}'}
)
print(response.json())Example: List Active Sessions (JavaScript)
JAVASCRIPT
const token = 'your_jwt_token';
fetch('https://ultravoice.us.inc/api/v1/sessions/active', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));WebSocket: Voice Pipeline Streaming
Real-time streaming pipeline for voice processing. Clients send 16kHz mono PCM audio (raw binary frames) or Twilio mulaw format. Server responds with JSON control messages and streamed TTS audio.
WebSocket URL
TEXT
wss://ultravoice.us.inc/api/v1/voice/ws/{session_id}Example: Connect to Voice Pipeline WebSocket
JAVASCRIPT
const sessionId = 'your_session_id';
const ws = new WebSocket(`wss://ultravoice.us.inc/api/v1/voice/ws/${sessionId}`);
ws.binaryType = 'arraybuffer';
ws.onopen = () => {
console.log('Connected to voice pipeline');
// Send raw 16kHz PCM audio
const audioBuffer = new ArrayBuffer(1024); // your audio data
ws.send(audioBuffer);
};
ws.onmessage = (event) => {
if (typeof event.data === 'string') {
// Control message (JSON)
const message = JSON.parse(event.data);
console.log('Message type:', message.type);
if (message.type === 'error') {
console.error('Error:', message.message);
} else if (message.type === 'call_ended') {
console.log('Call ended:', message.reason);
} else if (message.type === 'pipeline_ready') {
console.log('Pipeline ready');
}
} else {
// Binary audio response
console.log('Received audio frame of size:', event.data.byteLength);
}
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
ws.onclose = () => {
console.log('Disconnected from voice pipeline');
};WebSocket Message Types (Server → Client)
The voice pipeline server sends the following JSON message types:
- error: `{"type": "error", "message": "..."}`
- call_ended: `{"type": "call_ended", "reason": "..."}`
- pipeline_ready: `{"type": "pipeline_ready", ...}`
ℹ️
Additional audio/transcript/function-call frames use internal USF Pipeline binary/frame formats, not simple typed JSON.
WebSocket: Twilio Media Streams Bridge
Bridge for Twilio Media Streams integration. Delegates to the main voice pipeline WebSocket internally.
WebSocket URL
TEXT
wss://ultravoice.us.inc/api/v1/voice/ws/twilio/{call_id}ℹ️
(shape unverified) — full WebSocket message protocol details and internal frame structures require additional documentation.
Telephony
The Telephony API manages outbound and inbound calls with Twilio as the supported provider. It includes call lifecycle management, status tracking, campaign operations, and webhooks for call events. All authenticated endpoints require Bearer token authentication.
POST /telephony/calls/outbound
Start an outbound call. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/outbound \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_123",
"to_number": "+14155552671",
"from_number": "+14155552671"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
payload = {
"agent_id": "agent_123",
"to_number": "+14155552671",
"from_number": "+14155552671"
}
response = requests.post(
f"{BASE}/telephony/calls/outbound",
headers={"Authorization": f"Bearer {token}"},
json=payload
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const payload = {
agent_id: 'agent_123',
to_number: '+14155552671',
from_number: '+14155552671'
};
fetch('https://ultravoice.us.inc/api/v1/telephony/calls/outbound', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"call_id": "call_abc123",
"session_id": "session_xyz789",
"provider_call_sid": "CA1234567890abcdef",
"telephony_provider": "twilio",
"status": "initiated",
"to_number": "+14155552671",
"from_number": "+14155552671",
"agent_id": "agent_123"
}GET /telephony/calls
List all active calls. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/telephony/calls \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
response = requests.get(
f"{BASE}/telephony/calls",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
fetch('https://ultravoice.us.inc/api/v1/telephony/calls', {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"count": 2,
"calls": [
{
"call_id": "call_abc123",
"session_id": "session_xyz789",
"agent_id": "agent_123",
"status": "in_progress",
"direction": "outbound",
"to_number": "+14155552671",
"from_number": "+14155552671",
"telephony_provider": "twilio"
}
]
}GET /telephony/calls/{call_id}
Get detailed status of a specific call. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
call_id = "call_abc123"
response = requests.get(
f"{BASE}/telephony/calls/{call_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const callId = 'call_abc123';
fetch(`https://ultravoice.us.inc/api/v1/telephony/calls/${callId}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"call_id": "call_abc123",
"session_id": "session_xyz789",
"agent_id": "agent_123",
"status": "in_progress",
"direction": "outbound",
"to_number": "+14155552671",
"from_number": "+14155552671",
"telephony_provider": "twilio"
}POST /telephony/calls/{call_id}/end
End an active call. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/end \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
call_id = "call_abc123"
response = requests.post(
f"{BASE}/telephony/calls/{call_id}/end",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const callId = 'call_abc123';
fetch(`https://ultravoice.us.inc/api/v1/telephony/calls/${callId}/end`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"call_id": "call_abc123",
"status": "ended",
"message": "Call ended successfully"
}POST /telephony/calls/{call_id}/transfer
Transfer an active call to a human agent. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/transfer \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to_number": "+14155552672"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
call_id = "call_abc123"
payload = {
"to_number": "+14155552672"
}
response = requests.post(
f"{BASE}/telephony/calls/{call_id}/transfer",
headers={"Authorization": f"Bearer {token}"},
json=payload
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const callId = 'call_abc123';
const payload = {
to_number: '+14155552672'
};
fetch(`https://ultravoice.us.inc/api/v1/telephony/calls/${callId}/transfer`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"call_id": "call_abc123",
"transferred": true,
"to_number": "+14155552672"
}POST /telephony/calls/inbound
Webhook endpoint for inbound Twilio calls. No authentication required. Twilio sends form data with CallSid, From, To, and AccountSid. Returns TwiML XML.
BASH
# This is typically called by Twilio, not manually
# Example curl showing the form data Twilio would send:
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/inbound \
--data "CallSid=CA1234567890abcdef" \
--data "From=%2B14155552671" \
--data "To=%2B14155552672" \
--data "AccountSid=ACxxxxxxxxxxxxxxx"PYTHON
# This endpoint is called by Twilio webhooks
# Here is an example of validating and parsing the request:
from urllib.parse import parse_qs
# Simulated form data from Twilio
form_data = {
'CallSid': 'CA1234567890abcdef',
'From': '+14155552671',
'To': '+14155552672',
'AccountSid': 'ACxxxxxxxxxxxxxxx'
}
print(f"Call SID: {form_data['CallSid']}")
print(f"From: {form_data['From']}")
print(f"To: {form_data['To']}")JAVASCRIPT
// This endpoint is called by Twilio, not typically from client code
// Example response handler:
fetch('https://ultravoice.us.inc/api/v1/telephony/calls/inbound', {
method: 'POST',
body: new URLSearchParams({
'CallSid': 'CA1234567890abcdef',
'From': '+14155552671',
'To': '+14155552672',
'AccountSid': 'ACxxxxxxxxxxxxxxx'
})
})
.then(r => r.text())
.then(twiml => console.log(twiml));Response (TwiML XML):
TEXT
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Connect>
<Stream url="wss://..." />
</Connect>
</Response>POST /telephony/calls/{call_id}/status
Webhook callback from Twilio for call status updates. No authentication required. Twilio sends form data with CallStatus, CallDuration, and CallSid.
BASH
# Called by Twilio automatically
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/status \
--data "CallStatus=completed" \
--data "CallDuration=180" \
--data "CallSid=CA1234567890abcdef"PYTHON
# This is a Twilio webhook callback
# Example request Twilio would send:
form_data = {
'CallStatus': 'completed',
'CallDuration': '180',
'CallSid': 'CA1234567890abcdef'
}
print(f"Status: {form_data['CallStatus']}")
print(f"Duration: {form_data['CallDuration']} seconds")JAVASCRIPT
// Twilio status callback
fetch('https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/status', {
method: 'POST',
body: new URLSearchParams({
'CallStatus': 'completed',
'CallDuration': '180',
'CallSid': 'CA1234567890abcdef'
})
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"received": true
}POST /telephony/calls/{call_id}/recording
Webhook callback from Twilio when a recording completes. No authentication required. Twilio sends form data with RecordingUrl, RecordingSid, RecordingDuration, and RecordingStatus.
BASH
# Called by Twilio when recording completes
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/recording \
--data "RecordingUrl=https://api.twilio.com/recording.wav" \
--data "RecordingSid=RE1234567890abcdef" \
--data "RecordingDuration=180" \
--data "RecordingStatus=completed"PYTHON
# Twilio recording webhook
form_data = {
'RecordingUrl': 'https://api.twilio.com/recording.wav',
'RecordingSid': 'RE1234567890abcdef',
'RecordingDuration': '180',
'RecordingStatus': 'completed'
}
print(f"Recording URL: {form_data['RecordingUrl']}")
print(f"Duration: {form_data['RecordingDuration']} seconds")JAVASCRIPT
// Twilio recording callback
fetch('https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/recording', {
method: 'POST',
body: new URLSearchParams({
'RecordingUrl': 'https://api.twilio.com/recording.wav',
'RecordingSid': 'RE1234567890abcdef',
'RecordingDuration': '180',
'RecordingStatus': 'completed'
})
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"received": true
}POST /telephony/calls/{call_id}/amd
Webhook callback from Twilio for Answering Machine Detection (AMD) verdict. No authentication required.
BASH
# Called by Twilio when AMD detection completes
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/amd \
--data "AnsweredBy=human" \
--data "CallSid=CA1234567890abcdef"PYTHON
# Twilio AMD webhook
form_data = {
'AnsweredBy': 'human', # or 'machine' or 'timeout'
'CallSid': 'CA1234567890abcdef'
}
print(f"Answered by: {form_data['AnsweredBy']}")JAVASCRIPT
// Twilio AMD callback
fetch('https://ultravoice.us.inc/api/v1/telephony/calls/call_abc123/amd', {
method: 'POST',
body: new URLSearchParams({
'AnsweredBy': 'human',
'CallSid': 'CA1234567890abcdef'
})
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"received": true,
"action": "..."
}GET /telephony/capabilities
Get per-provider capabilities for Answering Machine Detection and voicemail features. No authentication required.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/telephony/capabilitiesPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(f"{BASE}/telephony/capabilities")
print(response.json())JAVASCRIPT
fetch('https://ultravoice.us.inc/api/v1/telephony/capabilities')
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"service": "twilio",
"providers": {
"twilio": {
"amd_supported": true,
"voicemail_supported": true
}
}
}GET /telephony/providers
List supported telephony providers. No authentication required.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/telephony/providersPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
response = requests.get(f"{BASE}/telephony/providers")
print(response.json())JAVASCRIPT
fetch('https://ultravoice.us.inc/api/v1/telephony/providers')
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"providers": [
{
"name": "twilio",
"supported": true
}
],
"count": 1
}GET /telephony/numbers
List Twilio phone numbers available in your workspace. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/telephony/numbers \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
response = requests.get(
f"{BASE}/telephony/numbers",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
fetch('https://ultravoice.us.inc/api/v1/telephony/numbers', {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"numbers": [
{
"sid": "PN1234567890abcdef",
"number": "+14155552671",
"friendly_name": "Support Line"
}
],
"count": 1
}GET /campaigns
List all campaigns. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/campaigns \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
response = requests.get(
f"{BASE}/campaigns",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
fetch('https://ultravoice.us.inc/api/v1/campaigns', {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": [
{
"campaign_id": "campaign_123",
"name": "Q1 Outreach",
"agent_id": "agent_123",
"status": "created"
}
]
}POST /campaigns
Create a new campaign. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/campaigns \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Q1 Outreach",
"agent_id": "agent_123",
"pacing_per_minute": 10,
"max_retries": 2
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
payload = {
"name": "Q1 Outreach",
"agent_id": "agent_123",
"pacing_per_minute": 10,
"max_retries": 2
}
response = requests.post(
f"{BASE}/campaigns",
headers={"Authorization": f"Bearer {token}"},
json=payload
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const payload = {
name: 'Q1 Outreach',
agent_id: 'agent_123',
pacing_per_minute: 10,
max_retries: 2
};
fetch('https://ultravoice.us.inc/api/v1/campaigns', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"name": "Q1 Outreach",
"agent_id": "agent_123",
"status": "created"
}
}GET /campaigns/{campaign_id}
Get campaign details. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/campaigns/campaign_123 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.get(
f"{BASE}/campaigns/{campaign_id}",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"name": "Q1 Outreach",
"agent_id": "agent_123",
"status": "created",
"pacing_per_minute": 10,
"max_retries": 2
}
}POST /campaigns/{campaign_id}/start
Start running a campaign. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/campaigns/campaign_123/start \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.post(
f"{BASE}/campaigns/{campaign_id}/start",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/start`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"status": "running"
}
}POST /campaigns/{campaign_id}/pause
Pause a running campaign. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/campaigns/campaign_123/pause \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.post(
f"{BASE}/campaigns/{campaign_id}/pause",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/pause`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"status": "paused"
}
}POST /campaigns/{campaign_id}/cancel
Cancel a campaign. Requires authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/campaigns/campaign_123/cancel \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.post(
f"{BASE}/campaigns/{campaign_id}/cancel",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/cancel`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"status": "cancelled"
}
}GET /campaigns/{campaign_id}/calls
List calls made by a campaign with optional pagination and status filtering. Requires authentication.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/campaigns/campaign_123/calls?page=1&per_page=50' \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.get(
f"{BASE}/campaigns/{campaign_id}/calls",
headers={"Authorization": f"Bearer {token}"},
params={"page": 1, "per_page": 50}
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
const params = new URLSearchParams({
page: '1',
per_page: '50'
});
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/calls?${params}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"calls": [
{
"call_id": "call_abc123",
"to_number": "+14155552671",
"status": "completed"
}
],
"page": 1,
"per_page": 50,
"total": 100,
"total_pages": 2
}
}POST /campaigns/{campaign_id}/csv-upload
Upload a CSV file with phone numbers for a campaign. Requires authentication and multipart form data.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/campaigns/campaign_123/csv-upload \
-H "Authorization: Bearer $TOKEN" \
-F "[email protected]"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
with open('contacts.csv', 'rb') as f:
files = {'file': f}
response = requests.post(
f"{BASE}/campaigns/{campaign_id}/csv-upload",
headers={"Authorization": f"Bearer {token}"},
files=files
)
print(response.json())JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
const formData = new FormData();
const fileInput = document.getElementById('csv-upload');
formData.append('file', fileInput.files[0]);
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/csv-upload`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: formData
})
.then(r => r.json())
.then(data => console.log(data));Response:
JSON
{
"success": true,
"data": {
"campaign_id": "campaign_123",
"rows_ingested": 500,
"rows_queued": 500
}
}GET /campaigns/{campaign_id}/export
Export campaign results as a CSV file. Requires authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/campaigns/campaign_123/export \
-H "Authorization: Bearer $TOKEN" \
-o campaign_results.csvPYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "YOUR_ACCESS_TOKEN"
campaign_id = "campaign_123"
response = requests.get(
f"{BASE}/campaigns/{campaign_id}/export",
headers={"Authorization": f"Bearer {token}"}
)
with open('campaign_results.csv', 'wb') as f:
f.write(response.content)
print("CSV exported successfully")JAVASCRIPT
const token = 'YOUR_ACCESS_TOKEN';
const campaignId = 'campaign_123';
fetch(`https://ultravoice.us.inc/api/v1/campaigns/${campaignId}/export`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
.then(r => r.blob())
.then(blob => {
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'campaign_results.csv';
a.click();
});Response:
TEXT
text/csv
phone_number,status,duration,outcome
+14155552671,completed,120,answered
+14155552672,completed,95,voicemail
+14155552673,failed,0,no_answerℹ️
All call and campaign operations use Twilio as the supported provider. Authentication is required for all user-facing endpoints except inbound webhooks from Twilio. WebSocket endpoints for real-time media streaming are available at wss://ultravoice.us.inc/api/v1/telephony/ws/media/{call_id} for Twilio media integration.
Conversations, Analysis & QA
Manage conversation logs, extract analysis schemas and results, run QA scoring and insights on agent interactions. Accessed via the conversation-logger backend at /api/v1/conversations/* (for messages and analysis) and /api/v1/qa/* (for rubrics and scoring). All endpoints require bearer authentication unless noted.
POST /conversations
Create a new conversation record. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/conversations \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_12345",
"user_id": "user_abc",
"agent_id": "agent_xyz",
"metadata": {"source": "web"}
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/conversations",
headers={"Authorization": f"Bearer {token}"},
json={
"session_id": "sess_12345",
"user_id": "user_abc",
"agent_id": "agent_xyz",
"metadata": {"source": "web"}
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch("https://ultravoice.us.inc/api/v1/conversations", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
session_id: "sess_12345",
user_id: "user_abc",
agent_id: "agent_xyz",
metadata: { source: "web" }
})
});
const data = await response.json();
console.log(data);Response: Conversation object with id, session_id, user_id, agent_id, status, metadata, created_at, updated_at.
GET /conversations
List conversations. Filter by agent_id, user_id, or workspace_id; supports pagination. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations?agent_id=agent_xyz&limit=20&offset=0" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations",
headers={"Authorization": f"Bearer {token}"},
params={
"agent_id": "agent_xyz",
"limit": 20,
"offset": 0
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz",
limit: "20",
offset: "0"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of Conversation objects with pagination metadata (page, per_page, total, total_pages).
GET /conversations/agent/{agentID}/count
Get conversation count for a specific agent. Requires bearer authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/conversations/agent/agent_xyz/count \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/agent/agent_xyz/count",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/agent/agent_xyz/count",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: {count: number}
GET /conversations/{id}
Get detailed conversation with all messages and tool calls. Requires bearer authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/conversations/conv_12345 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/conv_12345",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/conv_12345",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: ConversationDetail {conversation: {...}, messages: [...], tool_calls: [...]}
PUT /conversations/{id}
End or update conversation metadata (status, turn counts, latency metrics). Requires bearer authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/conversations/conv_12345 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "completed",
"total_turns": 15,
"total_duration_ms": 45000,
"avg_response_latency_ms": 250
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.put(
f"{BASE}/conversations/conv_12345",
headers={"Authorization": f"Bearer {token}"},
json={
"status": "completed",
"total_turns": 15,
"total_duration_ms": 45000,
"avg_response_latency_ms": 250
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/conv_12345",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
status: "completed",
total_turns: 15,
total_duration_ms: 45000,
avg_response_latency_ms: 250
})
}
);
const data = await response.json();
console.log(data);Response: {id: string, status: "completed"}
POST /conversations/messages
Log a message turn in a conversation. Supports role, content, tool calls, and metrics (ASR, LLM, TTS). Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/conversations/messages \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"conversation_id": "conv_12345",
"turn_number": 1,
"role": "user",
"content": "What is your pricing?",
"metadata": {"latency_ms": 100}
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/conversations/messages",
headers={"Authorization": f"Bearer {token}"},
json={
"conversation_id": "conv_12345",
"turn_number": 1,
"role": "user",
"content": "What is your pricing?",
"metadata": {"latency_ms": 100}
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/messages",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
conversation_id: "conv_12345",
turn_number: 1,
role: "user",
content: "What is your pricing?",
metadata: { latency_ms: 100 }
})
}
);
const data = await response.json();
console.log(data);Response: Message object with id, conversation_id, turn_number, role, content, metadata, created_at.
GET /conversations/{id}/messages
List all messages in a conversation. Requires bearer authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/conversations/conv_12345/messages \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/conv_12345/messages",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/conv_12345/messages",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of Message objects.
PATCH /conversations/messages/{messageID}
Update message metadata (e.g., annotation, flags). Requires bearer authentication.
BASH
curl -X PATCH https://ultravoice.us.inc/api/v1/conversations/messages/msg_abc \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"metadata": {"flagged": true, "reason": "unclear answer"}}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.patch(
f"{BASE}/conversations/messages/msg_abc",
headers={"Authorization": f"Bearer {token}"},
json={
"metadata": {"flagged": True, "reason": "unclear answer"}
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/messages/msg_abc",
{
method: "PATCH",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
metadata: { flagged: true, reason: "unclear answer" }
})
}
);
const data = await response.json();
console.log(data);Response: {id: string, status: "updated"}
POST /conversations/tool-calls
Log a tool call executed during conversation. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/conversations/tool-calls \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"conversation_id": "conv_12345",
"message_id": "msg_abc",
"tool_name": "booking_calendar",
"tool_input": {"date": "2025-01-15"},
"tool_output": {"available_slots": ["10:00", "14:00"]},
"status": "success",
"latency_ms": 500
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/conversations/tool-calls",
headers={"Authorization": f"Bearer {token}"},
json={
"conversation_id": "conv_12345",
"message_id": "msg_abc",
"tool_name": "booking_calendar",
"tool_input": {"date": "2025-01-15"},
"tool_output": {"available_slots": ["10:00", "14:00"]},
"status": "success",
"latency_ms": 500
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/tool-calls",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
conversation_id: "conv_12345",
message_id: "msg_abc",
tool_name: "booking_calendar",
tool_input: { date: "2025-01-15" },
tool_output: { available_slots: ["10:00", "14:00"] },
status: "success",
latency_ms: 500
})
}
);
const data = await response.json();
console.log(data);Response: ToolCall object with id, conversation_id, message_id, tool_name, input, output, status, latency_ms, created_at.
POST /conversations/analysis/schemas
Create an analysis schema for extracting structured insights from conversations. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/conversations/analysis/schemas \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_xyz",
"name": "Support Ticket Analysis",
"description": "Extract issue category, urgency, and resolution",
"fields": [
{"name": "issue_category", "type": "string"},
{"name": "urgency", "type": "string"},
{"name": "resolved", "type": "boolean"}
]
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/conversations/analysis/schemas",
headers={"Authorization": f"Bearer {token}"},
json={
"agent_id": "agent_xyz",
"name": "Support Ticket Analysis",
"description": "Extract issue category, urgency, and resolution",
"fields": [
{"name": "issue_category", "type": "string"},
{"name": "urgency", "type": "string"},
{"name": "resolved", "type": "boolean"}
]
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/analysis/schemas",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_id: "agent_xyz",
name: "Support Ticket Analysis",
description: "Extract issue category, urgency, and resolution",
fields: [
{ name: "issue_category", type: "string" },
{ name: "urgency", type: "string" },
{ name: "resolved", type: "boolean" }
]
})
}
);
const data = await response.json();
console.log(data);Response: AnalysisSchema object with id, agent_id, name, description, fields[], is_active, created_at, updated_at.
GET /conversations/analysis/schemas
List all analysis schemas for an agent. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations/analysis/schemas?agent_id=agent_xyz" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/analysis/schemas",
headers={"Authorization": f"Bearer {token}"},
params={"agent_id": "agent_xyz"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations/analysis/schemas?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of AnalysisSchema objects.
PUT /conversations/analysis/schemas/{schemaId}
Update an analysis schema (name, description, fields, or active status). Requires bearer authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/conversations/analysis/schemas/schema_123 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Enhanced Support Analysis",
"is_active": true
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.put(
f"{BASE}/conversations/analysis/schemas/schema_123",
headers={"Authorization": f"Bearer {token}"},
json={
"name": "Enhanced Support Analysis",
"is_active": True
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/analysis/schemas/schema_123",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Enhanced Support Analysis",
is_active: true
})
}
);
const data = await response.json();
console.log(data);Response: Updated AnalysisSchema object.
DELETE /conversations/analysis/schemas/{schemaId}
Delete an analysis schema. Requires bearer authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/conversations/analysis/schemas/schema_123 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.delete(
f"{BASE}/conversations/analysis/schemas/schema_123",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/conversations/analysis/schemas/schema_123",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: {status: "deleted"}
GET /conversations/analysis/results
Retrieve analysis results for conversations. Filter by conversation_id or agent_id. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations/analysis/results?agent_id=agent_xyz&limit=20&offset=0" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/analysis/results",
headers={"Authorization": f"Bearer {token}"},
params={
"agent_id": "agent_xyz",
"limit": 20,
"offset": 0
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz",
limit: "20",
offset: "0"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations/analysis/results?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of AnalysisResult objects with extracted fields and metadata.
GET /conversations/analysis/insights
Get agent-level insights aggregated from all conversation analyses. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations/analysis/insights?agent_id=agent_xyz" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/analysis/insights",
headers={"Authorization": f"Bearer {token}"},
params={"agent_id": "agent_xyz"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations/analysis/insights?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Insights object with aggregated metrics and patterns from conversation analyses.
GET /conversations/analytics/pipeline-events
Get pipeline event statistics (ASR, LLM, TTS processing). Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations/analytics/pipeline-events?agent_id=agent_xyz&from=2025-01-01&to=2025-01-31" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/analytics/pipeline-events",
headers={"Authorization": f"Bearer {token}"},
params={
"agent_id": "agent_xyz",
"from": "2025-01-01",
"to": "2025-01-31"
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz",
from: "2025-01-01",
to: "2025-01-31"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations/analytics/pipeline-events?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of event stats [{event_type, status, provider, model_id, total, avg_latency_ms, p95_latency_ms}, ...]
GET /conversations/analytics/pipeline-summary
Get summary of pipeline event success and failure rates by type. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/conversations/analytics/pipeline-summary?agent_id=agent_xyz&from=2025-01-01&to=2025-01-31" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/conversations/analytics/pipeline-summary",
headers={"Authorization": f"Bearer {token}"},
params={
"agent_id": "agent_xyz",
"from": "2025-01-01",
"to": "2025-01-31"
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
agent_id: "agent_xyz",
from: "2025-01-01",
to: "2025-01-31"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/conversations/analytics/pipeline-summary?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of summary stats [{event_type, status, total}, ...]
POST /qa/rubrics
Create a QA rubric with scoring criteria. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/qa/rubrics \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "ws_123",
"name": "Customer Service Quality",
"description": "Evaluate agent professionalism and issue resolution",
"criteria": [
{"name": "professionalism", "weight": 25},
{"name": "issue_resolved", "weight": 50},
{"name": "response_time", "weight": 25}
],
"pass_threshold": 70
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/qa/rubrics",
headers={"Authorization": f"Bearer {token}"},
json={
"workspace_id": "ws_123",
"name": "Customer Service Quality",
"description": "Evaluate agent professionalism and issue resolution",
"criteria": [
{"name": "professionalism", "weight": 25},
{"name": "issue_resolved", "weight": 50},
{"name": "response_time", "weight": 25}
],
"pass_threshold": 70
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/rubrics",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
workspace_id: "ws_123",
name: "Customer Service Quality",
description: "Evaluate agent professionalism and issue resolution",
criteria: [
{ name: "professionalism", weight: 25 },
{ name: "issue_resolved", weight: 50 },
{ name: "response_time", weight: 25 }
],
pass_threshold: 70
})
}
);
const data = await response.json();
console.log(data);Response: QARubric object with id, workspace_id, name, description, criteria, pass_threshold, created_at, updated_at.
GET /qa/rubrics
List all QA rubrics for a workspace. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/qa/rubrics?workspace_id=ws_123" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/qa/rubrics",
headers={"Authorization": f"Bearer {token}"},
params={"workspace_id": "ws_123"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
workspace_id: "ws_123"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/qa/rubrics?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of QARubric objects.
PUT /qa/rubrics/{rubricId}
Update a QA rubric (name, description, criteria, pass_threshold). Requires bearer authentication.
BASH
curl -X PUT https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Enhanced Service Quality",
"pass_threshold": 75
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.put(
f"{BASE}/qa/rubrics/rubric_456",
headers={"Authorization": f"Bearer {token}"},
json={
"name": "Enhanced Service Quality",
"pass_threshold": 75
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456",
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Enhanced Service Quality",
pass_threshold: 75
})
}
);
const data = await response.json();
console.log(data);Response: Updated QARubric object.
DELETE /qa/rubrics/{rubricId}
Delete a QA rubric. Requires bearer authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456 \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.delete(
f"{BASE}/qa/rubrics/rubric_456",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: {status: "deleted"}
POST /qa/rubrics/{rubricId}/bind/{agentId}
Assign a QA rubric to an agent. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456/bind/agent_xyz \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/qa/rubrics/rubric_456/bind/agent_xyz",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456/bind/agent_xyz",
{
method: "POST",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: {status: "bound"}
DELETE /qa/rubrics/{rubricId}/bind/{agentId}
Remove a QA rubric from an agent. Requires bearer authentication.
BASH
curl -X DELETE https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456/bind/agent_xyz \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.delete(
f"{BASE}/qa/rubrics/rubric_456/bind/agent_xyz",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/rubrics/rubric_456/bind/agent_xyz",
{
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: {status: "unbound"}
GET /qa/agent/{agentId}/rubric
Get the active QA rubric assigned to an agent. Requires bearer authentication.
BASH
curl -X GET https://ultravoice.us.inc/api/v1/qa/agent/agent_xyz/rubric \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/qa/agent/agent_xyz/rubric",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/agent/agent_xyz/rubric",
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: QARubric object or null if no rubric is assigned.
GET /qa/scores
Get QA scores for a conversation or cohort of conversations. Requires bearer authentication.
BASH
curl -X GET "https://ultravoice.us.inc/api/v1/qa/scores?conversation_id=conv_12345" \
-H "Authorization: Bearer $TOKEN"PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.get(
f"{BASE}/qa/scores",
headers={"Authorization": f"Bearer {token}"},
params={"conversation_id": "conv_12345"}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const params = new URLSearchParams({
conversation_id: "conv_12345"
});
const response = await fetch(
`https://ultravoice.us.inc/api/v1/qa/scores?${params}`,
{
method: "GET",
headers: { "Authorization": `Bearer ${token}` }
}
);
const data = await response.json();
console.log(data);Response: Array of QAScore objects (single conversation) OR array with pagination metadata for cohort queries. Use conversation_id for single score lookup or workspace_id+agent_id for cohort analysis.
POST /qa/scores/{scoreId}/review
Mark a QA score as reviewed with notes. Requires bearer authentication.
BASH
curl -X POST https://ultravoice.us.inc/api/v1/qa/scores/score_789/review \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"reviewer_id": "user_reviewer",
"notes": "Good call overall, needs improvement on hold times"
}'PYTHON
import requests
BASE = "https://ultravoice.us.inc/api/v1"
token = "your_access_token"
response = requests.post(
f"{BASE}/qa/scores/score_789/review",
headers={"Authorization": f"Bearer {token}"},
json={
"reviewer_id": "user_reviewer",
"notes": "Good call overall, needs improvement on hold times"
}
)
print(response.json())JAVASCRIPT
const token = "your_access_token";
const response = await fetch(
"https://ultravoice.us.inc/api/v1/qa/scores/score_789/review",
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
reviewer_id: "user_reviewer",
notes: "Good call overall, needs improvement on hold times"
})
}
);
const data = await response.json();
console.log(data);Response: {status: "reviewed"}
Analytics & Alerts
Monitor system performance, usage metrics, and configure alerting rules. All endpoints require Bearer token authentication.
GET /analytics/latency
Retrieve per-component latency metrics. Requires Bearer token. Query parameters: session_id (optional), agent_id (optional).
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/analytics/latency?agent_id=agent-123' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/analytics/latency', params={'agent_id': 'agent-123'}, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/analytics/latency?agent_id=agent-123', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of latency metrics with fields: metric_type, component, provider, model, avg_latency_ms, count.
GET /analytics/usage
Retrieve usage statistics across sessions and conversations. Requires Bearer token. Query parameters: user_id (optional), agent_id (optional).
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/analytics/usage?agent_id=agent-123' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/analytics/usage', params={'agent_id': 'agent-123'}, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/analytics/usage?agent_id=agent-123', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of usage records with fields: user_id, total_sessions, total_conversations, total_messages, total_duration_ms, avg_latency_ms, p95_latency_ms, p99_latency_ms.
GET /analytics/system-health
Retrieve latest system health status across all services. Requires Bearer token. No query parameters.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/analytics/system-health' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/analytics/system-health', headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/analytics/system-health', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of service health records with fields: service_name, status, cpu_usage, memory_usage, active_connections, request_count, error_count, avg_response_ms, recorded_at.
GET /analytics/tool-calls
Retrieve tool execution metrics including success rates and latency percentiles. Requires Bearer token. Query parameters: agent_id (optional), session_id (optional).
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/analytics/tool-calls?agent_id=agent-123' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/analytics/tool-calls', params={'agent_id': 'agent-123'}, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/analytics/tool-calls?agent_id=agent-123', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of tool metrics with fields: tool_name, call_count, success_count, error_count, success_rate, avg_latency_ms, min_latency_ms, max_latency_ms, p50_latency_ms, p95_latency_ms.
GET /alerts/rules
List all configured alert rules for the workspace. Requires Bearer token. No query parameters.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/alerts/rules' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/alerts/rules', headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/rules', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of AlertRule objects.
POST /alerts/rules
Create a new alert rule. Requires Bearer token. Required fields: name, metric, operator. Optional: scope, threshold, window_minutes, cooldown_minutes, channels (email, webhook, slack arrays).
BASH
curl -X POST 'https://ultravoice.us.inc/api/v1/alerts/rules' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "High error rate",
"metric": "error_rate",
"scope": "agent-123",
"operator": "greater_than",
"threshold": 5.0,
"window_minutes": 5,
"cooldown_minutes": 10,
"channels": {
"email": ["[email protected]"],
"webhook": ["https://example.com/alert"],
"slack": ["#alerts"]
}
}'PYTHON
import requests
import json
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
}
payload = {
'name': 'High error rate',
'metric': 'error_rate',
'scope': 'agent-123',
'operator': 'greater_than',
'threshold': 5.0,
'window_minutes': 5,
'cooldown_minutes': 10,
'channels': {
'email': ['[email protected]'],
'webhook': ['https://example.com/alert'],
'slack': ['#alerts']
}
}
response = requests.post(f'{BASE}/alerts/rules', json=payload, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const payload = {
name: 'High error rate',
metric: 'error_rate',
scope: 'agent-123',
operator: 'greater_than',
threshold: 5.0,
window_minutes: 5,
cooldown_minutes: 10,
channels: {
email: ['[email protected]'],
webhook: ['https://example.com/alert'],
slack: ['#alerts']
}
};
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/rules', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const data = await response.json();
console.log(data);Response: AlertRule object with id, name, metric, operator, threshold, and other fields.
PUT /alerts/rules/{id}
Update an existing alert rule. Requires Bearer token. All fields optional (pointers).
BASH
curl -X PUT 'https://ultravoice.us.inc/api/v1/alerts/rules/rule-456' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"threshold": 10.0,
"cooldown_minutes": 15
}'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
}
payload = {
'threshold': 10.0,
'cooldown_minutes': 15
}
response = requests.put(f'{BASE}/alerts/rules/rule-456', json=payload, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const payload = {
threshold: 10.0,
cooldown_minutes: 15
};
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/rules/rule-456', {
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const data = await response.json();
console.log(data);Response: Updated AlertRule object.
DELETE /alerts/rules/{id}
Delete an alert rule. Requires Bearer token.
BASH
curl -X DELETE 'https://ultravoice.us.inc/api/v1/alerts/rules/rule-456' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.delete(f'{BASE}/alerts/rules/rule-456', headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/rules/rule-456', {
method: 'DELETE',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: {deleted: true}.
GET /alerts/events
List alert events (triggered alerts). Requires Bearer token. Query parameters: status (optional), limit (optional, default 50).
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/alerts/events?status=active&limit=20' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/alerts/events', params={'status': 'active', 'limit': 20}, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/events?status=active&limit=20', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: Array of AlertEvent objects.
POST /alerts/events/{id}/resolve
Mark an alert event as resolved. Requires Bearer token.
BASH
curl -X POST 'https://ultravoice.us.inc/api/v1/alerts/events/event-789/resolve' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.post(f'{BASE}/alerts/events/event-789/resolve', headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/events/event-789/resolve', {
method: 'POST',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: {resolved: true}.
GET /alerts/active-count
Get the count of currently open alert events. Requires Bearer token.
BASH
curl -X GET 'https://ultravoice.us.inc/api/v1/alerts/active-count' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {'Authorization': 'Bearer YOUR_JWT_TOKEN'}
response = requests.get(f'{BASE}/alerts/active-count', headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/active-count', {
method: 'GET',
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data);Response: {count: number}.
POST /alerts/test
Test-fire an alert rule to verify configuration. Requires Bearer token. Request body: metric, scope, operator, threshold, window (uses same fields as CreateRuleRequest).
BASH
curl -X POST 'https://ultravoice.us.inc/api/v1/alerts/test' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "Test rule",
"metric": "error_rate",
"operator": "greater_than",
"threshold": 5.0,
"window_minutes": 5
}'PYTHON
import requests
BASE = 'https://ultravoice.us.inc/api/v1'
headers = {
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Content-Type': 'application/json'
}
payload = {
'name': 'Test rule',
'metric': 'error_rate',
'operator': 'greater_than',
'threshold': 5.0,
'window_minutes': 5
}
response = requests.post(f'{BASE}/alerts/test', json=payload, headers=headers)
print(response.json())JAVASCRIPT
const token = 'YOUR_JWT_TOKEN';
const payload = {
name: 'Test rule',
metric: 'error_rate',
operator: 'greater_than',
threshold: 5.0,
window_minutes: 5
};
const response = await fetch('https://ultravoice.us.inc/api/v1/alerts/test', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
const data = await response.json();
console.log(data);Response: {observed_value: number, threshold: number, operator: string, fired: boolean}.
Endpoints Pending Verification
A few endpoints could not be fully confirmed from the codebase and are documented conservatively — verify before relying on the exact request/response shape:
- providers: GET /providers/resolve - query params and response shape not confirmed in handler, marked for human verification before publishing
- sessions-ws: Sessions /active response shape unconfirmed in code
- sessions-ws: Full WebSocket message protocol (beyond error/call_ended/pipeline_ready) uses internal USF Pipeline frames
- sessions-ws: Session WS protocol at /sessions/ws not fully documented