# Knowledge and tools
Source: https://docs.mrassistant.ai/agents/knowledge-and-tools
Grounding and controlled actions for agents
Agents combine **what they know** (documents, policies, catalogs) with **what they can do** (lookups, bookings, tickets). Keeping those two concerns explicit helps B2C teams evolve assistants without surprise behavior.
## Knowledge
Ground answers in **approved content**: help articles, policy PDFs, product catalogs, or curated URLs. Refresh content on a schedule that matches how often your business changes.
## Tools
Tools are **discrete actions** the assistant may request. Good tools are **small**, **idempotent when possible**, and **easy to monitor** in production.
## Safety and quality
* Treat tool inputs as **untrusted** until validated by your services.
* Rate-limit downstream systems so viral traffic does not become an outage.
* Review transcripts regularly for **unexpected tool use** and **user confusion**.
## Related
# Agents
Source: https://docs.mrassistant.ai/agents/overview
Configure and run MrAssistant voice agents
An **agent** is the unit of configuration for a voice experience: instructions, model selection, voice, tools, and knowledge sources. You create and update agents through the HTTP API and manage them per tenant.
## Lifecycle
1. **Create** an agent with baseline instructions and provider defaults.
2. **Iterate** using partial updates as you tune prompts and behavior.
3. **Attach knowledge** when answers should be grounded in your documents or URLs.
4. **Enable tools** when the agent must call your APIs or built-in actions.
5. **Run conversations** or **sessions** against a stable agent id.
## API surface
The generated **API reference** lists routes under `/agents` (including documents, knowledge, tools, conversations, and sessions). Use request and response schemas from OpenAPI when building clients.
## Design tips
* Write **spoken** instructions: short sentences, explicit confirmation steps, and clear escalation paths.
* Keep **tool** contracts small and testable; validate arguments server-side.
* Use **multilingual** settings when callers may switch languages mid-session.
## Related
# API keys health check
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/api-keys-health-check
https://api.mrassistant.ai/openapi.json get /admin/api-keys/health
Quick health check of all API keys. **Requires admin authentication.**
# Get admin notifications
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/get-admin-notifications
https://api.mrassistant.ai/openapi.json get /admin/api-keys/notifications
Get admin notifications for API key issues with recommended actions. **Requires admin authentication.**
# Get API key issues
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/get-api-key-issues
https://api.mrassistant.ai/openapi.json get /admin/api-keys/issues
Get list of all current API key issues that need admin attention. **Requires admin authentication.**
# Get provider configuration requirements
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/get-provider-configuration-requirements
https://api.mrassistant.ai/openapi.json get /admin/api-keys/provider/{provider_id}/config
Get configuration requirements for a specific provider. **Requires admin authentication.**
# List all API keys
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/list-all-api-keys
https://api.mrassistant.ai/openapi.json get /admin/api-keys/list
Get complete list of all API keys needed for the platform with their configuration status. **Requires admin authentication.**
# List required API keys
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/list-required-api-keys
https://api.mrassistant.ai/openapi.json get /admin/api-keys/required
Get the complete list of environment variables needed for all providers. **Requires admin authentication.**
# Refresh validation cache
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/refresh-validation-cache
https://api.mrassistant.ai/openapi.json post /admin/api-keys/refresh-validation
Force re-validation of all API keys. **Requires admin authentication.**
# Validate all providers
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/validate-all-providers
https://api.mrassistant.ai/openapi.json get /admin/api-keys/validate
Validate API keys for all configured providers. **Requires admin authentication.**
# Validate single provider
Source: https://docs.mrassistant.ai/api-reference/admin--api-keys/validate-single-provider
https://api.mrassistant.ai/openapi.json get /admin/api-keys/validate/{provider_id}
Validate API key for a specific provider. **Requires admin authentication.**
# Bulk Configure Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/bulk-configure-providers
https://api.mrassistant.ai/openapi.json post /admin/providers/bulk-configure
Configure multiple providers at once.
# Get All Llm Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-all-llm-providers
https://api.mrassistant.ai/openapi.json get /admin/providers/llm
Get all available LLM providers with their models and languages.
Returns comprehensive list for frontend dropdown/selection.
Includes configured status, models, and language support.
# Get All Providers Summary
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-all-providers-summary
https://api.mrassistant.ai/openapi.json get /admin/providers/all
Get summary of all providers (LLM, TTS, STT) with language support.
Comprehensive endpoint for frontend to populate all dropdowns.
Includes language support for each provider.
# Get All Stt Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-all-stt-providers
https://api.mrassistant.ai/openapi.json get /admin/providers/stt
Get all available STT providers with their models and languages.
Returns comprehensive list for frontend transcription selection.
Includes language support and auto-detection capabilities.
# Get All Tts Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-all-tts-providers
https://api.mrassistant.ai/openapi.json get /admin/providers/tts
Get all available TTS providers with their voices and languages.
Returns comprehensive list for frontend voice selection.
Includes language support for each provider.
# Get All Tts Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-all-tts-providers-1
https://api.mrassistant.ai/openapi.json get /admin/providers/tts-providers
Get all available TTS providers with their voice options.
Updated with official LiveKit plugin configurations.
# Get Available Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-available-providers
https://api.mrassistant.ai/openapi.json get /admin/providers/available
Get all available service providers with real capabilities from APIs.
# Get Configured Providers
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-configured-providers
https://api.mrassistant.ai/openapi.json get /admin/providers/configured
Get currently configured service providers.
Voice processing is now handled by LiveKit voice worker with AgentFactory.
This endpoint returns the available providers from AgentFactory's registry.
# Get Llm Provider Details
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-llm-provider-details
https://api.mrassistant.ai/openapi.json get /admin/providers/llm/{provider}
Get detailed information about a specific LLM provider.
# Get Provider Cost Comparison
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-provider-cost-comparison
https://api.mrassistant.ai/openapi.json get /admin/providers/cost-comparison
Compare costs across different providers.
# Get Provider Languages
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-provider-languages
https://api.mrassistant.ai/openapi.json get /admin/providers/languages/{provider}
Get real supported languages for a specific provider.
# Get Provider Recommendations
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-provider-recommendations
https://api.mrassistant.ai/openapi.json get /admin/providers/recommendations
Get provider recommendations based on use case and requirements.
# Get Provider Setup Guide
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-provider-setup-guide
https://api.mrassistant.ai/openapi.json get /admin/providers/setup-guide/{provider}
Get detailed setup guide for a specific provider.
# Get Provider Voices
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-provider-voices
https://api.mrassistant.ai/openapi.json get /admin/providers/voices/{provider}
Get available voices for a provider and language.
# Get Providers By Language
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-providers-by-language
https://api.mrassistant.ai/openapi.json get /admin/providers/by-language/{language}
Get all providers that support a specific language.
Args:
language: Language code (e.g., "en", "es", "fr", "de", "zh", "ja")
Returns providers filtered by language support.
# Get Supported Languages
Source: https://docs.mrassistant.ai/api-reference/admin-providers/get-supported-languages
https://api.mrassistant.ai/openapi.json get /admin/providers/languages
Get all supported languages across all providers.
Returns language codes with provider support info.
Useful for filtering providers by language.
# Refresh Provider Capabilities
Source: https://docs.mrassistant.ai/api-reference/admin-providers/refresh-provider-capabilities
https://api.mrassistant.ai/openapi.json post /admin/providers/refresh-capabilities
Force refresh of provider capabilities from APIs.
# Test Provider Connection
Source: https://docs.mrassistant.ai/api-reference/admin-providers/test-provider-connection
https://api.mrassistant.ai/openapi.json post /admin/providers/test-connection
Test connection to a service provider.
# Validate Llm Provider
Source: https://docs.mrassistant.ai/api-reference/admin-providers/validate-llm-provider
https://api.mrassistant.ai/openapi.json post /admin/providers/validate/llm
Validate a single LLM provider configuration.
Checks:
- API key validity
- Model availability
# Validate Provider Configuration
Source: https://docs.mrassistant.ai/api-reference/admin-providers/validate-provider-configuration
https://api.mrassistant.ai/openapi.json post /admin/providers/validate
Validate provider configurations before creating or updating an agent.
This endpoint checks:
- API key validity for each provider
- Voice ID existence (for TTS providers like ElevenLabs, Cartesia)
- Model availability (for STT/LLM providers)
- Account quota status (where applicable)
Use this to pre-validate configurations before agent creation.
# Validate Stt Provider
Source: https://docs.mrassistant.ai/api-reference/admin-providers/validate-stt-provider
https://api.mrassistant.ai/openapi.json post /admin/providers/validate/stt
Validate a single STT provider configuration.
Checks:
- API key validity
- Model availability
# Validate Tts Provider
Source: https://docs.mrassistant.ai/api-reference/admin-providers/validate-tts-provider
https://api.mrassistant.ai/openapi.json post /admin/providers/validate/tts
Validate a single TTS provider configuration.
Checks:
- API key validity
- Voice ID existence and accessibility
- Account quota (for ElevenLabs)
# Validate Voice Id
Source: https://docs.mrassistant.ai/api-reference/admin-providers/validate-voice-id
https://api.mrassistant.ai/openapi.json get /admin/providers/validate/voice/{provider}/{voice_id}
Quick validation of a specific voice ID for a TTS provider.
Example:
GET /providers/validate/voice/elevenlabs/EXAVITQu4vr4xnSDxMaL
# Get Available Models
Source: https://docs.mrassistant.ai/api-reference/admin-services/get-available-models
https://api.mrassistant.ai/openapi.json get /admin/services/models/available
Get available models for ASR, TTS, and LLM services from AgentFactory.
# Get Providers Summary
Source: https://docs.mrassistant.ai/api-reference/admin-services/get-providers-summary
https://api.mrassistant.ai/openapi.json get /admin/services/providers/summary
Get summary of all available providers from AgentFactory.
# Get Service Configuration
Source: https://docs.mrassistant.ai/api-reference/admin-services/get-service-configuration
https://api.mrassistant.ai/openapi.json get /admin/services/configuration
Get current service configuration from AgentFactory.
# Get Services Health
Source: https://docs.mrassistant.ai/api-reference/admin-services/get-services-health
https://api.mrassistant.ai/openapi.json get /admin/services/health
Get health status of all voice processing services.
Voice processing is handled by the LiveKit voice worker using AgentFactory.
This endpoint returns the status of configured providers.
# Get Supported Languages
Source: https://docs.mrassistant.ai/api-reference/admin-services/get-supported-languages
https://api.mrassistant.ai/openapi.json get /admin/services/languages/supported
Get supported languages across all services.
# Test Voice Processing
Source: https://docs.mrassistant.ai/api-reference/admin-services/test-voice-processing
https://api.mrassistant.ai/openapi.json post /admin/services/test
Test voice processing services.
Note: Actual voice processing is handled by the LiveKit voice worker.
This endpoint validates configuration only.
# Block Tenant
Source: https://docs.mrassistant.ai/api-reference/admin/block-tenant
https://api.mrassistant.ai/openapi.json post /admin/tenants/{tenant_id}/block
Block or unblock a tenant from accessing services.
**Use when:**
- Tenant exceeds quota
- Payment issues
- Terms of service violations
- Manual suspension needed
**Block services:**
- `calls`: Block making/receiving calls
- `agents`: Block creating new agents
- `sip`: Block SIP/phone features
- `recordings`: Block recording access
- `analytics`: Block analytics access
# Get Billing Summary
Source: https://docs.mrassistant.ai/api-reference/admin/get-billing-summary
https://api.mrassistant.ai/openapi.json get /admin/billing/summary
Get billing summary for all tenants.
**For invoicing system - returns:**
- Per-tenant usage and charges
- Total platform revenue
- Breakdown by tenant type
# Get Platform Statistics
Source: https://docs.mrassistant.ai/api-reference/admin/get-platform-statistics
https://api.mrassistant.ai/openapi.json get /admin/stats
Get platform-wide statistics for admin dashboard.
**Returns:**
- Total/active/blocked tenants
- Total/active users
- Total/active agents
- Call statistics (today, month, all-time)
- Active sessions
- Revenue data
**Use for:**
- Admin dashboard overview
- Platform health monitoring
- Billing reports
# Get Tenant Details
Source: https://docs.mrassistant.ai/api-reference/admin/get-tenant-details
https://api.mrassistant.ai/openapi.json get /admin/tenants/{tenant_id}
Get detailed statistics for a specific tenant.
**Returns complete tenant profile including:**
- All tenant details
- Current usage (agents, calls, minutes)
- Quota configuration and status
- Billing information
- Last activity timestamp
# List All Agents Stats
Source: https://docs.mrassistant.ai/api-reference/admin/list-all-agents-stats
https://api.mrassistant.ai/openapi.json get /admin/agents
List all agents across all tenants with statistics.
**Returns per agent:**
- Agent details
- Call counts and minutes
- Average call duration
- Average sentiment score
- Last activity
# List All Tenants
Source: https://docs.mrassistant.ai/api-reference/admin/list-all-tenants
https://api.mrassistant.ai/openapi.json get /admin/tenants
List all tenants with summary statistics.
**For billing system integration - returns all tenants with:**
- Tenant details (name, type, plan, status)
- Usage counts (agents, calls)
- Quota status (exceeded or not)
**Filters:**
- `tenant_type`: business, developer, admin
- `status_filter`: active, blocked, suspended
# List All Users
Source: https://docs.mrassistant.ai/api-reference/admin/list-all-users
https://api.mrassistant.ai/openapi.json get /admin/users
List all users with tenant information.
**Returns:**
- User details (username, email, role)
- Associated tenant info
- Account status (active, verified)
# Reset Tenant Usage
Source: https://docs.mrassistant.ai/api-reference/admin/reset-tenant-usage
https://api.mrassistant.ai/openapi.json post /admin/billing/reset-usage/{tenant_id}
Reset tenant monthly usage counters (after billing cycle).
# Update Tenant Quota
Source: https://docs.mrassistant.ai/api-reference/admin/update-tenant-quota
https://api.mrassistant.ai/openapi.json put /admin/tenants/{tenant_id}/quota
Update tenant quota limits (tenure).
**Adjustable quotas:**
- `max_agents`: Maximum number of agents allowed
- `max_squads`: Maximum number of squads allowed
- `max_calls_per_month`: Monthly call limit
- `max_concurrent_calls`: Concurrent call limit
- `max_minutes_per_month`: Monthly minutes limit
- `max_campaigns`: Maximum campaigns allowed
- `max_recordings_gb`: Recording storage limit
- `max_files_gb`: File storage limit
- `max_file_size_mb`: Maximum single file size
# Update Tenant Type
Source: https://docs.mrassistant.ai/api-reference/admin/update-tenant-type
https://api.mrassistant.ai/openapi.json put /admin/tenants/{tenant_id}/type
Change tenant type (business/developer/admin).
**Tenant Types:**
- `business`: Uses platform API keys (default)
- `developer`: Can bring their own API keys (BYOK)
- `admin`: Internal admin access
# Bootstrap Agent
Source: https://docs.mrassistant.ai/api-reference/agent-bootstrap/bootstrap-agent
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/bootstrap
Aggregate a full snapshot of an agent's runtime configuration.
Returns: agent record fields, the attached workflow (if any), every tool
*instance* with its full config, every centralized transfer_target the
owner has, the tenant's handoff persona registry joined to the backing
agents (`available_specialists`), and tool_connection identifiers
(auth_payload is redacted so this is safe to ship to a voice worker).
# Chat With Agent
Source: https://docs.mrassistant.ai/api-reference/agent-chat/chat-with-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/chat
Send a text message to an agent and get a response.
This endpoint allows REST API-based interactions with agents,
useful for:
- Web chat interfaces
- API integrations
- Testing agent behavior
- Non-voice applications
Example:
```json
{
"query": "What is your refund policy?",
"conversation_id": "conv-123", // Optional, for follow-up
"top_k": 5
}
```
Response:
```json
{
"response": "Our refund policy allows...",
"payload": null,
"selected_tool": null,
"conversation_id": "conv-123",
"trace_id": "trace-abc",
"execution_time_ms": 850,
"versions": {"kb_v": "1.0", "policy_v": "1.0", "tools_v": "1.0"}
}
```
# Apply Use Case Template
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/apply-use-case-template
https://api.mrassistant.ai/openapi.json post /config/agents/{agent_id}/apply-template
Apply a use case template to an agent.
# Configure Agent
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/configure-agent
https://api.mrassistant.ai/openapi.json post /config/agents/{agent_id}/configure
Update agent configuration with enhanced settings.
# Create Template
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/create-template
https://api.mrassistant.ai/openapi.json post /config/templates
Create a custom agent template.
Allows users to create their own reusable templates for agent creation.
# Delete Template
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/delete-template
https://api.mrassistant.ai/openapi.json delete /config/templates/{template_id}
Delete a custom template.
# Estimate Agent Costs
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/estimate-agent-costs
https://api.mrassistant.ai/openapi.json post /config/agents/{agent_id}/estimate-costs
Estimate costs for an agent based on configuration and projected usage.
# Get All Voices With Previews
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-all-voices-with-previews
https://api.mrassistant.ai/openapi.json get /config/voices
Get all available voices from all TTS providers with preview URLs stored in MinIO.
This endpoint:
1. Fetches all voices from provider APIs (when configured)
2. Generates preview audio for all voices (pre-generated at startup)
3. Stores all previews in MinIO object storage
4. Returns MinIO URLs for all previews
**Comprehensive Filtering:**
- Provider: Filter by TTS provider
- Gender: male, female, neutral
- Language: Single language code (e.g., 'en', 'ta', 'hi')
- Languages: Multiple languages (comma-separated, e.g., 'en,es,fr')
- Accent: american, british, spanish, french, german, indian, etc.
- Age: young, middle_aged, old
- Tone: warm, professional, friendly, authoritative, energetic, etc.
- Use Case: voice_agents, customer_service, narration, marketing, etc.
- Recommended: Filter for recommended voices only
- Multilingual: Filter for multilingual voices only
- Region: africa, asia, europe, middle_east, oceania, global
- Primary Language: Filter by voice's primary language
**All previews are stored in MinIO and pre-generated at startup for fast access.**
# Get Available Providers
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-available-providers
https://api.mrassistant.ai/openapi.json get /config/providers/available
Get available providers for model, voice, and transcription.
# Get Available Voices
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-available-voices
https://api.mrassistant.ai/openapi.json get /config/agents/{agent_id}/voices
Get available voices for an agent based on its language configuration.
# Get Template
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-template
https://api.mrassistant.ai/openapi.json get /config/templates/{template_id}
Get a specific template by ID.
# Get Use Case Templates
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-use-case-templates
https://api.mrassistant.ai/openapi.json get /config/templates
Get all available templates (system built-in + user-created + public).
Returns both hardcoded templates and custom templates from database.
# Get Voice Filter Metadata
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/get-voice-filter-metadata
https://api.mrassistant.ai/openapi.json get /config/voices/filters
Get available filter options and metadata for voice selection.
**Frontend Usage:**
Use this endpoint to:
1. Build filter UI components (dropdowns, checkboxes, etc.)
2. Know which filters are available per provider
3. Understand filter types and their options
**Returns:**
- All available filter options
- Filter options per provider
- Filter descriptions and types
- Example filter combinations
# Refresh Voice Preview Urls
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/refresh-voice-preview-urls
https://api.mrassistant.ai/openapi.json post /config/voices/refresh-urls
Force refresh of all voice preview URLs.
This clears the cached preview URLs and regenerates them with correct public URLs.
Use this if preview URLs are returning internal/unreachable addresses.
**Admin/Debug endpoint** - typically only needed after server configuration changes.
# Update Template
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/update-template
https://api.mrassistant.ai/openapi.json put /config/templates/{template_id}
Update a custom template.
# Validate Agent Configuration
Source: https://docs.mrassistant.ai/api-reference/agent-configuration/validate-agent-configuration
https://api.mrassistant.ai/openapi.json get /config/agents/{agent_id}/validate
Validate agent configuration and get optimization suggestions.
# Add Knowledge Urls
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/add-knowledge-urls
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/knowledge/urls
Add knowledge base URLs to an existing agent.
**PHASE 3 MIGRATION**: Now scrapes websites locally and adds to knowledge base.
This endpoint:
- Fetches content from the provided URLs
- Extracts text from HTML
- Chunks and embeds the content locally
- Stores in local FAISS vector index
- Makes web content immediately searchable for RAG
Example:
```json
{
"urls": [
"https://company.com/about",
"https://docs.company.com/api-guide"
]
}
```
Supports:
- HTTP/HTTPS URLs
- HTML content extraction
- Concurrent fetching (up to 3 URLs at once)
- Automatic chunking and embedding
# Delete Document
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/delete-document
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/documents/{document_id}
Delete a specific document from the knowledge base.
This will:
- Remove the document file
- Delete all associated chunks
- Update the knowledge base index
Warning: This action is irreversible.
# Get Knowledge Base Stats
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/get-knowledge-base-stats
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/knowledge/stats
Get knowledge base statistics for an agent (Local System).
Returns:
- Total chunk count
- Current KB version
- Processing status
- Document count
Use this to:
- Monitor KB size and capacity
- Check processing status
- Debug KB issues
# Get Task Status
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/get-task-status
https://api.mrassistant.ai/openapi.json get /agents/tasks/{task_id}
Get the status of a background task.
Use this to track:
- Knowledge base processing
- Document uploads
- URL ingestion
Status values:
- `pending`: Task queued but not started
- `running`: Task is currently processing
- `completed`: Task finished successfully
- `failed`: Task encountered an error
Example:
```
GET /agents/tasks/task_abc123
```
# List Documents
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/list-documents
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/documents
List all documents in an agent's knowledge base (Local System).
Returns metadata for all uploaded documents including:
- Document ID
- Filename
- Content type
- Upload timestamp
- File size
# Reindex Knowledge Base
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/reindex-knowledge-base
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/knowledge/reindex
Trigger knowledge base reindexing (Local System).
Use this to:
- Fix broken/corrupted KB
- Update embeddings after changes
- Refresh stale data
In the local system, this rebuilds the FAISS index from stored documents.
# Upload Documents
Source: https://docs.mrassistant.ai/api-reference/agent-knowledge/upload-documents
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/documents/upload
Upload PDF/document files to an agent's knowledge base.
**PHASE 3 MIGRATION**: Now uses local vector store (FAISS) instead of external factory.
This endpoint:
- Accepts multiple PDF/document files
- Processes them locally (extract text, chunk, embed)
- Stores embeddings in local FAISS vector index
- Makes documents immediately searchable for RAG
Supported formats: PDF, TXT, DOCX, MD
Max file size: 10MB per file
# Activate Agent
Source: https://docs.mrassistant.ai/api-reference/agent-management/activate-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/activate
Activate an agent (move from draft to active).
# Clone Agent
Source: https://docs.mrassistant.ai/api-reference/agent-management/clone-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/clone
Clone an existing agent with modifications.
# Deactivate Agent
Source: https://docs.mrassistant.ai/api-reference/agent-management/deactivate-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/deactivate
Deactivate an agent (pause operations).
# Get Agent Configuration
Source: https://docs.mrassistant.ai/api-reference/agent-management/get-agent-configuration
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/configuration
Get complete agent configuration.
# Get Agent Statistics
Source: https://docs.mrassistant.ai/api-reference/agent-management/get-agent-statistics
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/stats
Get agent performance statistics.
# Get Agent Status
Source: https://docs.mrassistant.ai/api-reference/agent-management/get-agent-status
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/status
Get agent status (Local Agent System).
Returns comprehensive status including configuration,
knowledge base, tools, and operational metrics.
# List Agent Versions
Source: https://docs.mrassistant.ai/api-reference/agent-management/list-agent-versions
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/versions
List all versions of an agent.
# Test Agent Configuration
Source: https://docs.mrassistant.ai/api-reference/agent-management/test-agent-configuration
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/test
Test agent configuration with sample input.
# Bulk Upload Phone Numbers
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/bulk-upload-phone-numbers
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/phone-numbers/bulk-upload
Bulk upload phone numbers from CSV file.
CSV Format:
phone_number,provider,enable_outbound,outbound_address,outbound_transport,destination_country,media_encryption,krisp_enabled,auth_username,auth_password
Example CSV:
```
phone_number,provider,enable_outbound,outbound_address,outbound_transport,destination_country,media_encryption,krisp_enabled
+15551234567,twilio,true,sip.twilio.com,TCP,US,ALLOW,true
+15559876543,vonage,true,sip.nexmo.com,TLS,US,ALLOW,true
+918012345678,plivo,true,sip.plivo.com,TLS,IN,REQUIRE,true
```
This endpoint processes the CSV file and registers all phone numbers in bulk.
Each row is processed independently - partial success is possible.
# Check Phone Number Health
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/check-phone-number-health
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/phone-numbers/{phone_number}/health-check
Check phone number health and LiveKit sync status.
Verifies:
- Phone number exists in database
- Dispatch rule exists in LiveKit
- SIP trunk is healthy
- Configuration is valid
Returns:
{
"phone_number": "+15551234567",
"status": "healthy",
"checks": {
"database": true,
"dispatch_rule": true,
"sip_trunk": true,
"livekit_sync": true
},
"issues": []
}
# Delete Phone Number
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/delete-phone-number
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/phone-numbers/{phone_number}
Delete a phone number registration for an agent.
For LiveKit-managed numbers:
- Releases the phone number from LiveKit (you're still billed for the month)
- Deletes the dispatch rule
- Removes from database
For external provider numbers:
- Deletes the dispatch rule from LiveKit
- Removes from database
- You must manually remove the SIP URI from your provider's dashboard
# Diagnose Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/diagnose-sip-trunk
https://api.mrassistant.ai/openapi.json get /agents/sip/diagnose/{phone_number}
Diagnose SIP trunk configuration for a phone number.
Returns detailed information about:
- Whether a trunk exists in LiveKit
- Configured allowed_addresses (IP allowlist)
- Whether a dispatch rule exists
- Issues and recommendations
Use this to troubleshoot inbound calls not reaching LiveKit.
# Fix Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/fix-sip-trunk
https://api.mrassistant.ai/openapi.json post /agents/sip/fix-trunk/{phone_number}
Fix SIP trunk by deleting and recreating with correct IP allowlist.
Use this when inbound calls aren't reaching LiveKit due to IP allowlist issues.
**CAUTION**: This will:
1. Delete the existing trunk
2. Create a new trunk with correct provider IPs
3. The trunk_id will change
4. You may need to re-register the phone number to recreate dispatch rules
Args:
phone_number: The phone number to fix (E.164 format)
provider: SIP provider (telnyx, twilio, vonage, plivo, etc.)
# Get Phone Number
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/get-phone-number
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/phone-numbers/{phone_number}
Get a specific phone number configuration.
Returns complete phone number details including:
- SIP URI for provider configuration
- LiveKit dispatch rule ID
- Provider-specific setup instructions
- Outbound calling status
# Get Provider Sip Address
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/get-provider-sip-address
https://api.mrassistant.ai/openapi.json get /agents/provider-sip-address/{provider}
Get the default SIP address for a specific provider.
Args:
provider: Provider name (e.g., 'twilio', 'vonage-eu', 'telnyx')
Returns:
Default SIP address for the provider, or null if not recognized.
Note: For providers not in our list, you must provide a custom `outbound_address`
when registering a phone number with enable_outbound=true.
# Get Supported Providers
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/get-supported-providers
https://api.mrassistant.ai/openapi.json get /agents/supported-providers
Get list of supported SIP providers with their default outbound addresses.
Use this endpoint to populate a dropdown in the frontend for provider selection.
Each provider includes:
- id: Provider identifier (e.g., 'twilio', 'vonage-eu')
- name: Display name
- default_sip_address: Default SIP server address for outbound calls
- regions: Available regional variants
- notes: Additional information
Users can always override the SIP address by providing a custom `outbound_address`
when registering a phone number.
# List Phone Numbers
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/list-phone-numbers
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/phone-numbers
List all phone numbers registered for an agent.
# List Sip Trunks
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/list-sip-trunks
https://api.mrassistant.ai/openapi.json get /agents/sip/list-trunks
List all SIP inbound trunks from LiveKit.
Returns trunk details including:
- Trunk ID and name
- Phone numbers on each trunk
- Allowed addresses (IP allowlist)
- Authentication status
Use this to see what's configured in LiveKit.
# Register Phone Number
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/register-phone-number
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/phone-numbers
Register a phone number for an agent.
Two modes of operation:
1. **LiveKit Phone Numbers** (provider='livekit'):
- For numbers already purchased through LiveKit Cloud dashboard
- No SIP trunk configuration needed
- Simplified setup - just provide the phone number
- LiveKit automatically manages the infrastructure
2. **External SIP Providers** (twilio, vonage, telnyx, etc.):
- You must already own the phone number
- Creates SIP dispatch rule in LiveKit
- Returns SIP URI to configure in provider's dashboard
- Supports both inbound and outbound calling
# Update Phone Number
Source: https://docs.mrassistant.ai/api-reference/agent-phone-numbers/update-phone-number
https://api.mrassistant.ai/openapi.json patch /agents/{agent_id}/phone-numbers/{phone_number}
Update phone number configuration.
Supports partial updates:
- enable_outbound: Enable/disable outbound calling
- status: Change status (active, inactive, suspended)
- provider_config: Update provider-specific configuration
- metadata: Update metadata
**Note:** Changing core SIP settings (trunk IDs, dispatch rules) requires
deleting and re-registering the phone number.
**LiveKit Sync:** Status changes are reflected in LiveKit metadata,
but dispatch rules remain active. To fully remove from LiveKit, use DELETE.
# Delete Conversation
Source: https://docs.mrassistant.ai/api-reference/agent-sessions/delete-conversation
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/conversations/{conversation_id}
Delete a conversation and all its messages.
Use this to:
- Remove sensitive conversations
- Clean up test data
- Comply with data deletion requests
Warning: This action is irreversible.
# Get Conversation Detail
Source: https://docs.mrassistant.ai/api-reference/agent-sessions/get-conversation-detail
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/conversations/{conversation_id}
Get full conversation history with all messages.
Returns complete conversation transcript including:
- All user messages
- All agent responses
- Tool executions
- Timestamps
- Metadata
Use this for:
- Reviewing agent performance
- Debugging conversations
- Customer service audits
- Training data collection
Example response:
```json
{
"conversation_id": "conv-123",
"agent_id": "agent-456",
"created_at": "2025-11-25T10:00:00Z",
"updated_at": "2025-11-25T10:05:00Z",
"messages": [
{
"role": "user",
"content": "What is your refund policy?",
"timestamp": "2025-11-25T10:00:00Z"
},
{
"role": "assistant",
"content": "Our refund policy...",
"timestamp": "2025-11-25T10:00:02Z",
"metadata": {"selected_tool": null, "execution_time_ms": 850}
}
]
}
```
# Get Session Detail
Source: https://docs.mrassistant.ai/api-reference/agent-sessions/get-session-detail
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/sessions/{session_id}
Get session detail (alias for /conversations/{conversation_id}).
Returns full conversation history for a session.
# List Agent Conversations
Source: https://docs.mrassistant.ai/api-reference/agent-sessions/list-agent-conversations
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/conversations
List all conversation sessions for an agent.
Returns a paginated list of conversations with summary information.
Use this to:
- View conversation history
- Audit agent interactions
- Find specific conversations
- Track agent usage
Example response:
```json
{
"sessions": [
{
"conversation_id": "conv-123",
"created_at": "2025-11-25T10:00:00Z",
"updated_at": "2025-11-25T10:05:00Z",
"message_count": 12,
"last_message_preview": "Thank you for your help!"
}
],
"total": 45,
"limit": 10,
"offset": 0
}
```
# List Agent Sessions
Source: https://docs.mrassistant.ai/api-reference/agent-sessions/list-agent-sessions
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/sessions
List all chat sessions for an agent (alias for /conversations).
Returns a paginated list of sessions including:
- Session ID
- Start/end timestamps
- Message counts
- Status
Use this to track conversations during live text chat.
# Create Agent Tool
Source: https://docs.mrassistant.ai/api-reference/agent-tools/create-agent-tool
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/tools
Add a tool *instance* to an agent.
Multiple instances of the same tool_key are allowed as long as their
`instance_name` differs. The `instance_name` is the function name the LLM
will use when calling the tool, so it must be unique per agent and a
valid identifier (letters/digits/underscore/hyphen).
# Delete Agent Tool
Source: https://docs.mrassistant.ai/api-reference/agent-tools/delete-agent-tool
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/tools/{instance_name}
Soft-delete a tool instance (hard_delete=true to permanently remove).
# Execute Agent Tool
Source: https://docs.mrassistant.ai/api-reference/agent-tools/execute-agent-tool
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/tools/{instance_name}/execute
Execute a tool instance manually (for testing/direct invocation).
# Get Agent Tool
Source: https://docs.mrassistant.ai/api-reference/agent-tools/get-agent-tool
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/tools/{instance_name}
Get a specific tool instance by instance_name.
# List Agent Tools
Source: https://docs.mrassistant.ai/api-reference/agent-tools/list-agent-tools
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/tools
List all tool instances configured for an agent.
# List Available Tools
Source: https://docs.mrassistant.ai/api-reference/agent-tools/list-available-tools
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/tools/registry/available
List all tool *types* from the registry (one entry per tool_key).
# Update Agent Tool
Source: https://docs.mrassistant.ai/api-reference/agent-tools/update-agent-tool
https://api.mrassistant.ai/openapi.json patch /agents/{agent_id}/tools/{instance_name}
Patch a specific tool instance.
# Export Transcript
Source: https://docs.mrassistant.ai/api-reference/agent-transcripts/export-transcript
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/transcripts/{session_id}/export
Export transcript in various formats.
Supports JSON, plain text, and CSV formats.
# Get Transcript
Source: https://docs.mrassistant.ai/api-reference/agent-transcripts/get-transcript
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/transcripts/{session_id}
Get full transcript for a specific session.
Returns the complete conversation history with all messages,
metadata, and AI-generated summary/analysis.
The `ai_summary` field contains:
- **summary**: Concise overview of the conversation
- **sentiment**: Sentiment analysis with score (-1.0 to 1.0)
- **topics**: Main topics discussed
- **action_items**: Any follow-up actions identified
- **key_moments**: Important turning points
- **outcome**: How the call concluded (resolved, escalated, etc.)
- **call_type**: Type of call (support, sales, inquiry, etc.)
Set `include_ai_summary=false` to skip AI analysis and reduce latency.
# List Transcripts
Source: https://docs.mrassistant.ai/api-reference/agent-transcripts/list-transcripts
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/transcripts
List all transcripts for an agent.
Returns a paginated list of conversation transcripts with summary information.
# Summarize Transcript
Source: https://docs.mrassistant.ai/api-reference/agent-transcripts/summarize-transcript
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/transcripts/{session_id}/summarize
Generate or regenerate AI summary for a transcript.
Use this endpoint to:
- Get a fresh summary with custom parameters
- Regenerate a summary with different options
- Generate summary for transcripts that didn't have one
**Cost note**: Each call uses OpenAI API tokens.
# Create Agent
Source: https://docs.mrassistant.ai/api-reference/agents/create-agent
https://api.mrassistant.ai/openapi.json post /agents
Create a new agent using LiveKit Cloud for all media/dispatch config.
# Create Agent With Documents
Source: https://docs.mrassistant.ai/api-reference/agents/create-agent-with-documents
https://api.mrassistant.ai/openapi.json post /agents/multipart
Create a new agent with document uploads (integrated with External Factory).
This endpoint allows creating an agent and uploading knowledge base documents in one request.
Uses the integrated CreateAgentUseCase with file support.
# Delete Agent
Source: https://docs.mrassistant.ai/api-reference/agents/delete-agent
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}
Delete agent using integrated use case.
This will:
- Delete ALL phone numbers associated with the agent
- Clean up ALL LiveKit resources (inbound trunks, outbound trunks, dispatch rules)
- Delete the agent's knowledge base
- Delete the agent from the database (cascades to tools, sessions, etc.)
# Delete Agent Legacy
Source: https://docs.mrassistant.ai/api-reference/agents/delete-agent-legacy
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/legacy
Delete agent from local database.
**Use DELETE /{agent_id} instead - it provides more comprehensive cleanup.**
This legacy endpoint:
- Delete agent from local database
- Delete all associated data (sessions, knowledge base, etc.)
# Disable Tool For Agent
Source: https://docs.mrassistant.ai/api-reference/agents/disable-tool-for-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/tools/{tool_key}/disable
Disable a tool for an agent.
# Enable Tool For Agent
Source: https://docs.mrassistant.ai/api-reference/agents/enable-tool-for-agent
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/tools/{tool_key}/enable
Enable a tool for an agent.
# Generate a full system prompt from a short brief
Source: https://docs.mrassistant.ai/api-reference/agents/generate-a-full-system-prompt-from-a-short-brief
https://api.mrassistant.ai/openapi.json post /agents/generate-system-prompt
Expand a 1-2 sentence brief into a production-ready voice-agent system prompt.
The frontend's "Generate" button hits this. The result is returned, not
stored — the operator reviews/edits before posting it as `system_prompt`
in the agent create/update payload.
# Get Agent
Source: https://docs.mrassistant.ai/api-reference/agents/get-agent
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}
Get agent by ID.
# Get Available Tools
Source: https://docs.mrassistant.ai/api-reference/agents/get-available-tools
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/tools/available
Get available tools for an agent.
# List Agents
Source: https://docs.mrassistant.ai/api-reference/agents/list-agents
https://api.mrassistant.ai/openapi.json get /agents
List agents for the current user.
# Update Agent
Source: https://docs.mrassistant.ai/api-reference/agents/update-agent
https://api.mrassistant.ai/openapi.json put /agents/{agent_id}
Update agent using integrated use case.
# Update Agent Old
Source: https://docs.mrassistant.ai/api-reference/agents/update-agent-old
https://api.mrassistant.ai/openapi.json put /agents/{agent_id}_old
Update agent (old implementation - deprecated).
# Upload Documents
Source: https://docs.mrassistant.ai/api-reference/agents/upload-documents
https://api.mrassistant.ai/openapi.json post /agents/{agent_id}/documents
Upload documents to agent knowledge base using integrated use case.
# Analytics Health
Source: https://docs.mrassistant.ai/api-reference/analytics/analytics-health
https://api.mrassistant.ai/openapi.json get /analytics/health
Check analytics service health.
Returns:
- Service enabled status
- LiveKit connectivity
- Redis connectivity
# Calls By Region
Source: https://docs.mrassistant.ai/api-reference/analytics/calls-by-region
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/calls/by-region
Worldwide call distribution — calls aggregated by caller country.
Powers the dashboard's "calls by region" map (choropleth keyed on ISO-2
country codes). Country is derived from the caller's E.164 number at
call-creation time via libphonenumber.
**Response shape:**
```json
{
"tenant_id": "...",
"period": {"start": "2026-03-18T00:00:00Z", "end": "2026-04-17T23:59:59Z"},
"regions": [
{"country_code": "US", "country_name": "United States",
"call_count": 1423, "total_minutes": 8921.5,
"avg_duration_sec": 376, "inbound": 1200, "outbound": 223}
],
"total_calls": 1735,
"countries_count": 47,
"calls_without_country": 12
}
```
Sorted by `call_count` DESC. `country_code` uses ISO 3166-1 alpha-2.
Calls with no parseable phone number (web sessions, anonymous calls)
are reported as `calls_without_country`.
# Export Calls
Source: https://docs.mrassistant.ai/api-reference/analytics/export-calls
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/export/calls
Export call data for tenant.
# Generate Report
Source: https://docs.mrassistant.ai/api-reference/analytics/generate-report
https://api.mrassistant.ai/openapi.json post /analytics/tenants/{tenant_id}/reports/generate
Generate analytics report for tenant.
# Get Agent Performance
Source: https://docs.mrassistant.ai/api-reference/analytics/get-agent-performance
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/agents/performance
Get performance metrics for a specific agent.
Metrics include:
- Call volume and success rate
- Average call duration
- Tool execution statistics
- Performance trends
# Get Call Statistics
Source: https://docs.mrassistant.ai/api-reference/analytics/get-call-statistics
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/calls
Get call statistics for a time period.
Statistics include:
- Total calls
- Success rate
- Average duration
- Failed calls
Can be filtered by specific agent.
# Get Capacity Metrics
Source: https://docs.mrassistant.ai/api-reference/analytics/get-capacity-metrics
https://api.mrassistant.ai/openapi.json get /analytics/capacity
Get system capacity and utilization metrics.
Shows:
- Current active calls
- Total system capacity
- Utilization percentage
- Available capacity
- Number of agents
# Get Dashboard Analytics
Source: https://docs.mrassistant.ai/api-reference/analytics/get-dashboard-analytics
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/dashboard
Get comprehensive analytics for tenant dashboard.
This is the main endpoint for dashboard rendering.
Returns all metrics in one response:
- Real-time metrics
- Call statistics
- Capacity metrics
- Per-agent performance
Use this endpoint to populate the main dashboard view.
Example Response:
```json
{
"tenant_id": "...",
"generated_at": "2025-12-04T10:00:00Z",
"period_hours": 24,
"real_time": {
"active_calls": 5,
"active_participants": 10,
"active_agents": 5
},
"call_statistics": {
"total_calls": 150,
"success_rate": 95.5,
"avg_duration_seconds": 180
},
"capacity": {
"current_active_calls": 5,
"total_capacity": 50,
"utilization_percentage": 10.0
},
"agents": [
{
"agent_id": "...",
"agent_name": "Customer Support Agent",
"calls": {...},
"tools": {...}
}
]
}
```
# Get Realtime Metrics
Source: https://docs.mrassistant.ai/api-reference/analytics/get-realtime-metrics
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/metrics/real-time
Get real-time metrics for current tenant.
Returns current system state:
- Active calls
- Active participants
- Active agents
Updates every 60 seconds (configurable).
# Get Tenant Quota
Source: https://docs.mrassistant.ai/api-reference/analytics/get-tenant-quota
https://api.mrassistant.ai/openapi.json get /analytics/tenants/{tenant_id}/quota
Get quota and remaining calls information for tenant.
Returns:
- Monthly call limit and remaining calls
- Concurrent call limit and available slots
- Total minutes used
- Quota exceeded status
# Change Password
Source: https://docs.mrassistant.ai/api-reference/authentication/change-password
https://api.mrassistant.ai/openapi.json post /auth/change-password
Change user password.
# Confirm Password Reset
Source: https://docs.mrassistant.ai/api-reference/authentication/confirm-password-reset
https://api.mrassistant.ai/openapi.json post /auth/reset-password/confirm
Confirm password reset with token.
# Delete Account
Source: https://docs.mrassistant.ai/api-reference/authentication/delete-account
https://api.mrassistant.ai/openapi.json delete /auth/account
Deactivate the current user's account.
Sets is_active=False so the user can no longer login.
Account data is preserved for audit purposes.
# Get User Info
Source: https://docs.mrassistant.ai/api-reference/authentication/get-user-info
https://api.mrassistant.ai/openapi.json get /auth/me
Get current user information.
# Login
Source: https://docs.mrassistant.ai/api-reference/authentication/login
https://api.mrassistant.ai/openapi.json post /auth/token
Login and get access token.
**PERMANENT AUTHENTICATION:**
- Users are retrieved from PostgreSQL database
- owner_id is PERMANENT and never changes
- Your agents will ALWAYS be accessible
# Logout
Source: https://docs.mrassistant.ai/api-reference/authentication/logout
https://api.mrassistant.ai/openapi.json post /auth/logout
Logout the current user.
Note: JWT tokens are stateless, so this endpoint confirms the logout.
The frontend should discard the tokens. For token blacklisting,
Redis-based revocation can be added later.
# Refresh Token
Source: https://docs.mrassistant.ai/api-reference/authentication/refresh-token
https://api.mrassistant.ai/openapi.json post /auth/refresh
Refresh access token using refresh token.
**How it works:**
- Client sends refresh_token (30-day validity)
- Server verifies refresh_token
- Server issues new access_token (24-hour validity)
- Server issues new refresh_token (30-day validity)
**Use this when:**
- Access token expires (after 24 hours)
- You want to extend user session without re-login
# Request Password Reset
Source: https://docs.mrassistant.ai/api-reference/authentication/request-password-reset
https://api.mrassistant.ai/openapi.json post /auth/reset-password
Request password reset token.
# Resend Verification
Source: https://docs.mrassistant.ai/api-reference/authentication/resend-verification
https://api.mrassistant.ai/openapi.json post /auth/resend-verification
Resend email verification token for the current user.
# Set Password
Source: https://docs.mrassistant.ai/api-reference/authentication/set-password
https://api.mrassistant.ai/openapi.json post /auth/set-password
Set a password for an OAuth user who doesn't have one.
This lets OAuth users add password login to their account.
# Sign Up
Source: https://docs.mrassistant.ai/api-reference/authentication/sign-up
https://api.mrassistant.ai/openapi.json post /auth/signup
Sign up a new user and auto-create tenant for business users.
**PERMANENT USER STORAGE:**
- Users are stored in PostgreSQL database
- owner_id is generated ONCE and persists forever
- Agents are NEVER lost because owner_id never changes
**User Roles:**
- **BUSINESS**: Organization owner - automatically gets a tenant created
- **DEVELOPER**: Technical user - no tenant created (uses platform features only)
**What happens during signup:**
1. User account is created in DATABASE (not memory)
2. If role=BUSINESS → Tenant (organization) is automatically created
3. User becomes the owner of their tenant
4. Tenant ID = owner_id (for consistency)
**Business User Flow:**
- Sign up → Tenant auto-created → Create agents → Make calls
**Developer User Flow:**
- Sign up → Access platform APIs → No tenant needed
# Update User Profile
Source: https://docs.mrassistant.ai/api-reference/authentication/update-user-profile
https://api.mrassistant.ai/openapi.json put /auth/profile
Update user profile.
# Verify Email
Source: https://docs.mrassistant.ai/api-reference/authentication/verify-email
https://api.mrassistant.ai/openapi.json post /auth/verify
Verify user email with JWT token.
# Delete Caller Profile
Source: https://docs.mrassistant.ai/api-reference/caller-profiles/delete-caller-profile
https://api.mrassistant.ai/openapi.json delete /caller-profiles/agents/{agent_id}/{phone}
Delete (forget) a caller profile. Past call records are preserved.
The next call from this number will be treated as a first-time call.
# Get Caller Calls
Source: https://docs.mrassistant.ai/api-reference/caller-profiles/get-caller-calls
https://api.mrassistant.ai/openapi.json get /caller-profiles/agents/{agent_id}/{phone}/calls
List past calls for a caller with this agent.
# Get Caller Profile
Source: https://docs.mrassistant.ai/api-reference/caller-profiles/get-caller-profile
https://api.mrassistant.ai/openapi.json get /caller-profiles/agents/{agent_id}/{phone}
Get a single caller profile for a specific (agent, phone) pair.
# List Caller Profiles
Source: https://docs.mrassistant.ai/api-reference/caller-profiles/list-caller-profiles
https://api.mrassistant.ai/openapi.json get /caller-profiles
List caller profiles for the current tenant. Most recently active first.
# Update Caller Profile
Source: https://docs.mrassistant.ai/api-reference/caller-profiles/update-caller-profile
https://api.mrassistant.ai/openapi.json patch /caller-profiles/agents/{agent_id}/{phone}
Update name / notes / language on a caller profile.
# Control Call
Source: https://docs.mrassistant.ai/api-reference/calls/control-call
https://api.mrassistant.ai/openapi.json post /calls/{call_id}/control
Real-time call control using LiveKit room and participant APIs.
# End Call
Source: https://docs.mrassistant.ai/api-reference/calls/end-call
https://api.mrassistant.ai/openapi.json post /calls/{call_id}/end
End a call.
# Get Active Calls
Source: https://docs.mrassistant.ai/api-reference/calls/get-active-calls
https://api.mrassistant.ai/openapi.json get /calls/agent/{agent_id}/active
Get currently active calls for a specific agent.
**Returns:**
- All calls with status 'initiated', 'ringing', or 'answered' (not ended)
- Real-time call information
- Recording status
# Get Call Artifact
Source: https://docs.mrassistant.ai/api-reference/calls/get-call-artifact
https://api.mrassistant.ai/openapi.json get /calls/{call_id}/artifact
Get call artifacts from LiveKit Egress recordings and transcripts.
# Get Call Recording
Source: https://docs.mrassistant.ai/api-reference/calls/get-call-recording
https://api.mrassistant.ai/openapi.json get /calls/{call_id}/recording
Get call recording information and download URL from MinIO storage.
**Restriction**: Recording must be enabled for the agent in agent configuration.
# Get Call Status
Source: https://docs.mrassistant.ai/api-reference/calls/get-call-status
https://api.mrassistant.ai/openapi.json get /calls/{call_id}
Get call status and details.
# Initiate Outbound Call
Source: https://docs.mrassistant.ai/api-reference/calls/initiate-outbound-call
https://api.mrassistant.ai/openapi.json post /calls/outbound
Initiate an outbound call from an agent.
# List Agent Calls
Source: https://docs.mrassistant.ai/api-reference/calls/list-agent-calls
https://api.mrassistant.ai/openapi.json get /calls/agent/{agent_id}/calls
List all calls for a specific agent with filtering and pagination.
**Returns:**
- Actual call records from the database
- Proper to/from phone numbers
- Correct inbound/outbound direction
- Recording information if available
# Mute Call
Source: https://docs.mrassistant.ai/api-reference/calls/mute-call
https://api.mrassistant.ai/openapi.json post /calls/{call_id}/mute
Mute/unmute call participant.
# Transfer Call
Source: https://docs.mrassistant.ai/api-reference/calls/transfer-call
https://api.mrassistant.ai/openapi.json post /calls/{call_id}/transfer
Transfer a call to another number or SIP endpoint.
Supports two transfer types:
- cold: Direct transfer, agent disconnects immediately
- warm: Agent provides context before connecting (requires additional orchestration)
The transfer_to parameter must be in one of these formats:
- tel:+15105550100 (phone number)
- sip:user@domain.com (SIP endpoint)
- sip:+15105550100@sip.telnyx.com (phone via SIP URI)
# Transfer Call Simple
Source: https://docs.mrassistant.ai/api-reference/calls/transfer-call-simple
https://api.mrassistant.ai/openapi.json post /calls/{call_id}/transfer/simple
[DEPRECATED] Simple call transfer endpoint.
**Use POST /{call_id}/transfer instead - it provides full implementation.**
This is a placeholder implementation that returns a mock transfer ID.
# Create Campaign
Source: https://docs.mrassistant.ai/api-reference/campaigns/create-campaign
https://api.mrassistant.ai/openapi.json post /campaigns
Create an outbound calling campaign.
This allows you to:
- Call multiple numbers in sequence or parallel
- Schedule calls for a specific time
- Set concurrent call limits
- Retry failed calls automatically
- Track campaign progress
# ============================================
# QUOTA ENFORCEMENT
# ============================================
# Get Campaign Status
Source: https://docs.mrassistant.ai/api-reference/campaigns/get-campaign-status
https://api.mrassistant.ai/openapi.json get /campaigns/{campaign_id}
Get campaign status and progress.
# List Campaigns
Source: https://docs.mrassistant.ai/api-reference/campaigns/list-campaigns
https://api.mrassistant.ai/openapi.json get /campaigns
List all campaigns for the current user.
Returns paginated list of campaigns with filtering by status.
# Delete File
Source: https://docs.mrassistant.ai/api-reference/files/delete-file
https://api.mrassistant.ai/openapi.json delete /files/{file_id}
Delete a file from storage and database.
# Download File
Source: https://docs.mrassistant.ai/api-reference/files/download-file
https://api.mrassistant.ai/openapi.json get /files/{file_id}/download
Download a file with presigned URL.
# Get File
Source: https://docs.mrassistant.ai/api-reference/files/get-file
https://api.mrassistant.ai/openapi.json get /files/{file_id}
Get a specific file.
# Get File Status
Source: https://docs.mrassistant.ai/api-reference/files/get-file-status
https://api.mrassistant.ai/openapi.json get /files/{file_id}/status
Get file processing status.
# Get Sync Status
Source: https://docs.mrassistant.ai/api-reference/files/get-sync-status
https://api.mrassistant.ai/openapi.json get /files/{file_id}/sync-status
Get detailed sync status including external agent task status.
# List Files
Source: https://docs.mrassistant.ai/api-reference/files/list-files
https://api.mrassistant.ai/openapi.json get /files
List files for the current user/tenant.
# Sync File To Agent
Source: https://docs.mrassistant.ai/api-reference/files/sync-file-to-agent
https://api.mrassistant.ai/openapi.json post /files/{file_id}/sync
Sync a file to an agent's knowledge base.
# Upload File
Source: https://docs.mrassistant.ai/api-reference/files/upload-file
https://api.mrassistant.ai/openapi.json post /files/upload
Upload a file to the knowledge base.
# Handle Livekit Webhook
Source: https://docs.mrassistant.ai/api-reference/handle-livekit-webhook
https://api.mrassistant.ai/openapi.json post /webhooks/livekit
# Health Check
Source: https://docs.mrassistant.ai/api-reference/health-check
https://api.mrassistant.ai/openapi.json get /health
Health check endpoint.
# Create Integration
Source: https://docs.mrassistant.ai/api-reference/integrations/create-integration
https://api.mrassistant.ai/openapi.json post /integrations
Create a new integration.
# Delete Integration
Source: https://docs.mrassistant.ai/api-reference/integrations/delete-integration
https://api.mrassistant.ai/openapi.json delete /integrations/{integration_id}
Delete an integration.
# Get Available Providers
Source: https://docs.mrassistant.ai/api-reference/integrations/get-available-providers
https://api.mrassistant.ai/openapi.json get /integrations/available/providers
Get available integration providers.
# Get Integration
Source: https://docs.mrassistant.ai/api-reference/integrations/get-integration
https://api.mrassistant.ai/openapi.json get /integrations/{integration_id}
Get a specific integration.
# List Integrations
Source: https://docs.mrassistant.ai/api-reference/integrations/list-integrations
https://api.mrassistant.ai/openapi.json get /integrations
List integrations for the current tenant.
# Test Integration
Source: https://docs.mrassistant.ai/api-reference/integrations/test-integration
https://api.mrassistant.ai/openapi.json post /integrations/{integration_id}/test
Test an integration connection by making a test API call.
# Update Integration
Source: https://docs.mrassistant.ai/api-reference/integrations/update-integration
https://api.mrassistant.ai/openapi.json put /integrations/{integration_id}
Update an integration.
# API overview
Source: https://docs.mrassistant.ai/api-reference/introduction
How to use the public API description alongside these guides
The MrAssistant HTTP API is described by a published **OpenAPI** document. The **Endpoints** section of this site is generated from that description so it stays aligned with the product.
## Specification
Your engineering team can import the machine-readable file from the **OpenAPI** link in the site header when they need request and response schemas, or browse **Endpoints** in this tab.
## Base URL
Production traffic uses the **api** host for MrAssistant; exact paths and versioning appear in the OpenAPI listing your team imports.
## Using the reference responsibly
* Treat the API reference as **engineering documentation**, not end-user help.
* Prefer **organization standards** for environments, change management, and review of generated clients.
## Major areas (conceptual)
| Area | Typical focus |
| -------------- | --------------------------------------------------- |
| Agents | Configuration, conversations, and related resources |
| Providers | Speech and language stack choices |
| Voice services | Realtime connectivity and regional options |
| Platform | Organization-level boundaries and operational views |
For **consumer-facing** explanations, stay in the **Documentation** tab; use the API reference when you are implementing or reviewing integrations.
# Liveness Check
Source: https://docs.mrassistant.ai/api-reference/liveness-check
https://api.mrassistant.ai/openapi.json get /health/live
Kubernetes liveness probe - checks if app is running.
# Cleanup Old Logs
Source: https://docs.mrassistant.ai/api-reference/logs/cleanup-old-logs
https://api.mrassistant.ai/openapi.json post /logs/cleanup
Clean up old logs based on retention policy.
# Delete Log
Source: https://docs.mrassistant.ai/api-reference/logs/delete-log
https://api.mrassistant.ai/openapi.json delete /logs/{log_id}
Delete a log entry.
# Export Logs
Source: https://docs.mrassistant.ai/api-reference/logs/export-logs
https://api.mrassistant.ai/openapi.json get /logs/export/{log_type}
Export logs in various formats (JSON, CSV, or Excel).
# Get Call Logs
Source: https://docs.mrassistant.ai/api-reference/logs/get-call-logs
https://api.mrassistant.ai/openapi.json get /logs/calls
Get call logs.
# Get Call Logs Detailed
Source: https://docs.mrassistant.ai/api-reference/logs/get-call-logs-detailed
https://api.mrassistant.ai/openapi.json get /logs/calls/{call_id}
Get detailed logs for a specific call.
# Get Chat Logs
Source: https://docs.mrassistant.ai/api-reference/logs/get-chat-logs
https://api.mrassistant.ai/openapi.json get /logs/chats
Get chat logs.
# Get Session Logs
Source: https://docs.mrassistant.ai/api-reference/logs/get-session-logs
https://api.mrassistant.ai/openapi.json get /logs/sessions
Get session logs.
# Get Session Logs Detailed
Source: https://docs.mrassistant.ai/api-reference/logs/get-session-logs-detailed
https://api.mrassistant.ai/openapi.json get /logs/sessions/{session_id}
Get detailed logs for a specific session.
# Get System Logs
Source: https://docs.mrassistant.ai/api-reference/logs/get-system-logs
https://api.mrassistant.ai/openapi.json get /logs/system
Get system logs.
# Mcp Jsonrpc
Source: https://docs.mrassistant.ai/api-reference/mcp/mcp-jsonrpc
https://api.mrassistant.ai/openapi.json post /mcp
Single MCP endpoint — dispatches `tools/list`, `tools/call`, `ping`.
# Mcp Manifest
Source: https://docs.mrassistant.ai/api-reference/mcp/mcp-manifest
https://api.mrassistant.ai/openapi.json get /mcp/manifest
Public discovery manifest — no auth required.
# Metrics
Source: https://docs.mrassistant.ai/api-reference/metrics
https://api.mrassistant.ai/openapi.json get /metrics
Prometheus metrics endpoint.
# List Oauth Providers
Source: https://docs.mrassistant.ai/api-reference/oauth/list-oauth-providers
https://api.mrassistant.ai/openapi.json get /auth/oauth/providers
Returns which OAuth providers are configured and available.
Frontend uses this to show/hide social login buttons.
# Oauth Authorize
Source: https://docs.mrassistant.ai/api-reference/oauth/oauth-authorize
https://api.mrassistant.ai/openapi.json get /auth/oauth/{provider}/authorize
Returns the OAuth authorization URL for the given provider.
Frontend should redirect the user to this URL.
# Oauth Callback
Source: https://docs.mrassistant.ai/api-reference/oauth/oauth-callback
https://api.mrassistant.ai/openapi.json get /auth/oauth/{provider}/callback
Handles the OAuth callback. Exchanges the authorization code for user info,
creates or finds the user, and returns JWT tokens.
The frontend should verify the state parameter matches what was returned
by /authorize before calling this endpoint.
# Check Can Call
Source: https://docs.mrassistant.ai/api-reference/outbound-config/check-can-call
https://api.mrassistant.ai/openapi.json get /outbound/agents/{agent_id}/can-call
Check if agent can make an outbound call right now.
This checks:
- Current time against calling schedules
- Daily call limits
- Concurrent call limits
- Do Not Call lists (if enabled)
- Recipient timezone (if enabled)
# Configure Outbound Calling
Source: https://docs.mrassistant.ai/api-reference/outbound-config/configure-outbound-calling
https://api.mrassistant.ai/openapi.json post /outbound/agents/{agent_id}/outbound-config
Configure outbound calling for an agent.
This allows you to:
- Set multiple outbound phone numbers (caller IDs)
- Define calling schedules with time windows
- Set daily call limits
- Configure timezone-aware calling hours
- Set concurrent call limits
# ============================================
# QUOTA ENFORCEMENT
# ============================================
# Get Outbound Config
Source: https://docs.mrassistant.ai/api-reference/outbound-config/get-outbound-config
https://api.mrassistant.ai/openapi.json get /outbound/agents/{agent_id}/outbound-config
Get outbound calling configuration for an agent.
# Create Persona
Source: https://docs.mrassistant.ai/api-reference/personas/create-persona
https://api.mrassistant.ai/openapi.json post /personas
# Delete Persona
Source: https://docs.mrassistant.ai/api-reference/personas/delete-persona
https://api.mrassistant.ai/openapi.json delete /personas/{persona_id}
# Get Persona
Source: https://docs.mrassistant.ai/api-reference/personas/get-persona
https://api.mrassistant.ai/openapi.json get /personas/{persona_id}
# Get Persona By Type
Source: https://docs.mrassistant.ai/api-reference/personas/get-persona-by-type
https://api.mrassistant.ai/openapi.json get /personas/by-type/{specialist_type}
Resolve a specialist_type slug → persona row (for handoff resolution).
# List Personas
Source: https://docs.mrassistant.ai/api-reference/personas/list-personas
https://api.mrassistant.ai/openapi.json get /personas
# Update Persona
Source: https://docs.mrassistant.ai/api-reference/personas/update-persona
https://api.mrassistant.ai/openapi.json patch /personas/{persona_id}
# Get Platform Demo Info
Source: https://docs.mrassistant.ai/api-reference/platform/get-platform-demo-info
https://api.mrassistant.ai/openapi.json get /platform/demo
Get platform demo and trial information.
# Get Platform Voice Options
Source: https://docs.mrassistant.ai/api-reference/platform/get-platform-voice-options
https://api.mrassistant.ai/openapi.json get /platform/voice-options
Get voice service options that users can select and configure on your platform.
# Get Pricing Calculator
Source: https://docs.mrassistant.ai/api-reference/platform/get-pricing-calculator
https://api.mrassistant.ai/openapi.json get /platform/pricing/calculator
Calculate estimated pricing for platform usage.
# Get Supported Languages
Source: https://docs.mrassistant.ai/api-reference/platform/get-supported-languages
https://api.mrassistant.ai/openapi.json get /platform/supported-languages
Get languages supported by the platform.
# Get Agent Config Schema
Source: https://docs.mrassistant.ai/api-reference/providers/get-agent-config-schema
https://api.mrassistant.ai/openapi.json get /providers/agent-config/schema
📋 Get complete schema for agent voice configuration.
**Frontend Usage:**
Use this to build forms for agent creation/editing with proper validation.
# Get All Languages
Source: https://docs.mrassistant.ai/api-reference/providers/get-all-languages
https://api.mrassistant.ai/openapi.json get /providers/languages
🌍 Get all supported languages with full metadata.
**Frontend Usage:**
Use this to populate language selection dropdowns.
**Returns:**
- Language code (ISO 639-1)
- Language name in English
- Native name
- Region
# Get All Llm Models
Source: https://docs.mrassistant.ai/api-reference/providers/get-all-llm-models
https://api.mrassistant.ai/openapi.json get /providers/llm/models
🧠 Get all available LLM models across all providers.
**Frontend Usage:**
Use this to populate model selection dropdowns with filtering.
**Query Parameters:**
- `provider`: Filter by provider (openai, anthropic, groq, etc.)
- `capability`: Filter by capability (fast, multimodal, standard, reasoning, coding)
- `max_latency_ms`: Filter by maximum latency
# Get All Llm Models Comprehensive
Source: https://docs.mrassistant.ai/api-reference/providers/get-all-llm-models-comprehensive
https://api.mrassistant.ai/openapi.json get /providers/llm/models/comprehensive
🧠 Get ALL LLM models with complete language support and capabilities.
**Frontend Usage:**
Use this to show which LLM models support which languages and capabilities.
**Returns:**
All LLM providers with models, languages per model, and capabilities.
# Get All Stt Models
Source: https://docs.mrassistant.ai/api-reference/providers/get-all-stt-models
https://api.mrassistant.ai/openapi.json get /providers/stt/models
🎧 Get ALL STT (transcriber) models with complete language support data.
**Frontend Usage:**
Use this to show which transcription models support which languages.
**Returns:**
All STT models with languages per model, including OpenAI Whisper.
# Get All Tts Voices
Source: https://docs.mrassistant.ai/api-reference/providers/get-all-tts-voices
https://api.mrassistant.ai/openapi.json get /providers/tts/voices
🎤 Get all available TTS voices across all providers.
**Frontend Usage:**
Use this to populate voice selection dropdowns with filtering.
**Query Parameters:**
- `provider`: Filter by provider (elevenlabs, openai, cartesia, deepgram)
- `gender`: Filter by gender (male, female, neutral)
- `language`: Filter by language code (e.g., 'en', 'es', 'zh')
# Get Available Providers
Source: https://docs.mrassistant.ai/api-reference/providers/get-available-providers
https://api.mrassistant.ai/openapi.json get /providers/available
Get all configured and available providers.
**Developer Workflow:**
1. Call this endpoint to discover what providers you can use
2. Use the returned provider names when creating agents
3. System validates that you're using configured providers
# Get Language Provider Support
Source: https://docs.mrassistant.ai/api-reference/providers/get-language-provider-support
https://api.mrassistant.ai/openapi.json get /providers/languages/{language_code}
🌍 Get provider support for a specific language.
**Returns:**
- Which TTS providers support this language
- Which STT providers support this language
- Recommended provider combinations
- Model-specific support
# Get Language Support Matrix
Source: https://docs.mrassistant.ai/api-reference/providers/get-language-support-matrix
https://api.mrassistant.ai/openapi.json get /providers/languages/matrix
🌍 Get comprehensive language support matrix for ALL providers.
**Frontend Usage:**
Use this to show which languages are supported by which providers/models.
**Returns:**
- TTS providers with models and their supported languages
- STT providers with models and their supported languages
- LLM providers with models and their supported languages
- Language-to-provider mapping for quick lookup
# Get Llm Api Keys Status
Source: https://docs.mrassistant.ai/api-reference/providers/get-llm-api-keys-status
https://api.mrassistant.ai/openapi.json get /providers/llm/api-keys
🔑 Get status of all LLM provider API keys.
**Frontend Usage:**
Check which LLM providers are configured and which need API keys.
**Returns:**
- List of configured providers
- List of missing API keys with environment variable names
- Setup instructions
# Get Llm Provider Details
Source: https://docs.mrassistant.ai/api-reference/providers/get-llm-provider-details
https://api.mrassistant.ai/openapi.json get /providers/llm/providers/{provider}
🧠 Get detailed information for a specific LLM provider.
**Includes:**
- All models with latency, pricing, capabilities
- Configuration status
- Recommended configurations for different use cases
- Required environment variables
# Get Llm Providers Comprehensive
Source: https://docs.mrassistant.ai/api-reference/providers/get-llm-providers-comprehensive
https://api.mrassistant.ai/openapi.json get /providers/llm/providers
🧠 Get ALL LLM (Language Model) providers with complete configuration data.
**Frontend Usage:**
Use this to populate model provider selection dropdowns and show capabilities.
**Returns for each provider:**
- Available models with latency, pricing, capabilities
- Configuration status
- Recommended models for voice agents
- API key requirements
**Example Response:**
```json
{
"providers": {
"openai": {
"name": "OpenAI",
"configured": true,
"models": {...},
"default_model": "gpt-4o-mini",
"recommended_for_voice_agents": "gpt-4o-mini"
}
}
}
```
# Get Providers Summary
Source: https://docs.mrassistant.ai/api-reference/providers/get-providers-summary
https://api.mrassistant.ai/openapi.json get /providers/summary
📊 Get a high-level summary of all providers and their capabilities.
Quick reference for what's available in the system.
# Get Recommended Agent Config
Source: https://docs.mrassistant.ai/api-reference/providers/get-recommended-agent-config
https://api.mrassistant.ai/openapi.json get /providers/agent-config/recommended
🤖 Get recommended provider configuration for creating an agent.
**Frontend Usage:**
Call this when user selects language/use case to auto-populate provider fields.
**Parameters:**
- `language`: Primary language (e.g., 'en', 'es', 'zh')
- `use_case`: voice_agent, customer_support, call_center
- `priority`: speed, quality, cost, balanced
**Returns:**
Ready-to-use agent configuration with recommended providers.
# Get Stt Provider Details
Source: https://docs.mrassistant.ai/api-reference/providers/get-stt-provider-details
https://api.mrassistant.ai/openapi.json get /providers/stt/providers/{provider}
🎧 Get detailed information for a specific STT provider.
# Get Stt Providers Comprehensive
Source: https://docs.mrassistant.ai/api-reference/providers/get-stt-providers-comprehensive
https://api.mrassistant.ai/openapi.json get /providers/stt/providers
🎧 Get ALL STT (Speech-to-Text) providers with complete configuration data.
**Frontend Usage:**
Use this to populate STT provider selection and show language support.
**Returns for each provider:**
- Available models with language support
- Real-time/streaming capabilities
- Diarization support
- Agent configuration examples
# Get Tts Provider Details
Source: https://docs.mrassistant.ai/api-reference/providers/get-tts-provider-details
https://api.mrassistant.ai/openapi.json get /providers/tts/providers/{provider}
🎙️ Get detailed information for a specific TTS provider.
**Includes:**
- All models with language support details
- All voices with metadata
- Configuration examples
- Language matrix
# Get Tts Providers Comprehensive
Source: https://docs.mrassistant.ai/api-reference/providers/get-tts-providers-comprehensive
https://api.mrassistant.ai/openapi.json get /providers/tts/providers
🎙️ Get ALL TTS providers with complete configuration data.
**Frontend Usage:**
Use this to populate provider selection dropdowns and show capabilities.
**Returns for each provider:**
- Available models with language support
- Pre-built voices with metadata
- Latency and quality information
- Configuration status
- Agent configuration examples
**Example Response:**
```json
{
"providers": {
"elevenlabs": {
"name": "ElevenLabs",
"configured": true,
"models": [...],
"voices": [...],
"max_languages": 74,
"recommended_model": "eleven_flash_v2_5"
}
}
}
```
# Get Tts Voices By Provider
Source: https://docs.mrassistant.ai/api-reference/providers/get-tts-voices-by-provider
https://api.mrassistant.ai/openapi.json get /providers/tts/voices/{provider}
🎤 Get ALL voices for a specific TTS provider with full metadata.
**Frontend Usage:**
Use this to populate voice selection with filtering by gender, accent, and language.
**Parameters:**
- `provider`: elevenlabs, openai, cartesia, deepgram
- `gender`: Filter by gender (male, female, neutral)
- `accent`: Filter by accent (american, british, indian, etc)
- `language`: Filter by primary or supported language
**Returns:**
Complete voice data with gender, accent, tone, and language support.
# Search Voices
Source: https://docs.mrassistant.ai/api-reference/providers/search-voices
https://api.mrassistant.ai/openapi.json get /providers/voices/search
🔍 Search and filter voices across all providers.
**Frontend Usage:**
Use this for advanced voice search with multiple filters.
**Example:**
- /voices/search?language=ta&gender=female - Tamil female voices
- /voices/search?accent=british&for_voice_agents=true - British voices for agents
# Validate Provider Configuration
Source: https://docs.mrassistant.ai/api-reference/providers/validate-provider-configuration
https://api.mrassistant.ai/openapi.json get /providers/validate
Validate if a provider is configured and available.
# Readiness Check
Source: https://docs.mrassistant.ai/api-reference/readiness-check
https://api.mrassistant.ai/openapi.json get /health/ready
Kubernetes readiness probe - checks if app is ready to serve traffic.
# Delete Recording
Source: https://docs.mrassistant.ai/api-reference/recordings/delete-recording
https://api.mrassistant.ai/openapi.json delete /agents/{agent_id}/recordings/{recording_id}
Delete a call recording.
This removes the recording from both MinIO storage and the database.
**Warning**: This action is irreversible.
# Get Recording
Source: https://docs.mrassistant.ai/api-reference/recordings/get-recording
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/recordings/{recording_id}
Get a specific recording with download URL.
Returns full recording details including a presigned download URL.
The URL is time-limited and expires after the specified duration.
**Restriction**: Recording must be enabled for the agent in agent configuration.
**Security**: URL expires after `url_expires` seconds (default: 1 hour).
# Get Recording Download Url
Source: https://docs.mrassistant.ai/api-reference/recordings/get-recording-download-url
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/recordings/{recording_id}/download-url
Get a fresh download URL for a recording.
Generates a new presigned URL with custom expiration time.
Useful for refreshing expired URLs without fetching full recording details.
**Restriction**: Recording must be enabled for the agent in agent configuration.
# List Agent Recordings
Source: https://docs.mrassistant.ai/api-reference/recordings/list-agent-recordings
https://api.mrassistant.ai/openapi.json get /agents/{agent_id}/recordings
List all call recordings for an agent.
**Restriction**: Recording must be enabled for the agent in agent configuration.
Returns a paginated list of recordings with metadata.
Each recording includes file information, status, and timestamps.
# Create Outbound Trunk
Source: https://docs.mrassistant.ai/api-reference/sip/create-outbound-trunk
https://api.mrassistant.ai/openapi.json post /sip/tenants/{tenant_id}/sip-trunks/outbound
⚠️ **DEPRECATED ENDPOINT** - This endpoint is no longer supported.
**Use Instead:** `POST /agents/{agent_id}/phone-numbers`
**Why Deprecated:**
- This endpoint used an incorrect SIP architecture
- It doesn't properly integrate with LiveKit dispatch rules
- Phone numbers should be registered at agent level, not tenant level
**Migration Guide:**
1. Use `POST /agents/{agent_id}/phone-numbers` to register phone numbers
2. See `CORRECT_PHONE_NUMBER_SETUP.md` for complete setup instructions
3. See `MULTI_AGENT_ARCHITECTURE_PLAN.md` for migration details
**Correct Endpoint:**
```
POST /agents/{agent_id}/phone-numbers
{
"phone_number": "+15551234567",
"provider": "twilio",
"enable_outbound": true,
"outbound_address": "sip.twilio.com"
}
```
# Delete Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/sip/delete-sip-trunk
https://api.mrassistant.ai/openapi.json delete /sip/tenants/{tenant_id}/sip-trunks/{trunk_id}
Delete SIP trunk.
# Get Agent Phone Numbers Summary
Source: https://docs.mrassistant.ai/api-reference/sip/get-agent-phone-numbers-summary
https://api.mrassistant.ai/openapi.json get /sip/agents/{agent_id}/phone-numbers-summary
Get a summary of agent's phone numbers and SIP configuration.
**Simpler Alternative:** Use `GET /api/v1/agents/{agent_id}/phone-numbers` for just the phone list
**What this returns:**
- All registered phone numbers with SIP URIs
- LiveKit SIP domain configuration
- Setup guide for new phone registration
**Use Cases:**
- Dashboard overview of agent's phone configuration
- Debugging SIP setup
- Migration from legacy trunk system
# Get Sip Configuration Docs
Source: https://docs.mrassistant.ai/api-reference/sip/get-sip-configuration-docs
https://api.mrassistant.ai/openapi.json get /sip/tenants/{tenant_id}/sip-config
Get SIP configuration documentation for a tenant.
# Get Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/sip/get-sip-trunk
https://api.mrassistant.ai/openapi.json get /sip/tenants/{tenant_id}/sip-trunks/{trunk_id}
Get SIP trunk by ID.
# Health Check Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/sip/health-check-sip-trunk
https://api.mrassistant.ai/openapi.json post /sip/tenants/{tenant_id}/sip-trunks/{trunk_id}/health-check
Perform health check on SIP trunk.
# List Sip Trunks
Source: https://docs.mrassistant.ai/api-reference/sip/list-sip-trunks
https://api.mrassistant.ai/openapi.json get /sip/tenants/{tenant_id}/sip-trunks
⚠️ **DEPRECATED ENDPOINT** - This endpoint is no longer supported.
**Use Instead:** `GET /agents/{agent_id}/phone-numbers`
**For listing all phone numbers across agents:**
- Use `GET /phone-numbers/all` (admin endpoint)
- Or iterate through agents: `GET /agents/{agent_id}/phone-numbers` for each agent
# Update Sip Trunk
Source: https://docs.mrassistant.ai/api-reference/sip/update-sip-trunk
https://api.mrassistant.ai/openapi.json put /sip/tenants/{tenant_id}/sip-trunks/{trunk_id}
Update SIP trunk.
# Create Squad Outbound Campaign
Source: https://docs.mrassistant.ai/api-reference/squad-calls/create-squad-outbound-campaign
https://api.mrassistant.ai/openapi.json post /squad-calls/squads/{squad_id}/outbound-campaign
Create an outbound calling campaign using a squad.
The campaign will be distributed across squad members based on:
- Agent availability
- Agent calling schedules
- Agent daily limits
- Squad routing strategy
Example:
```json
{
"squad_id": "squad-uuid",
"name": "Q4 Sales Campaign",
"targets": [
{"to_number": "+1234567890", "context": {"customer_id": "123"}},
{"to_number": "+0987654321", "context": {"customer_id": "456"}}
],
"routing_strategy": "load_based",
"concurrent_calls_per_agent": 2
}
```
# Get Squad Call Stats
Source: https://docs.mrassistant.ai/api-reference/squad-calls/get-squad-call-stats
https://api.mrassistant.ai/openapi.json get /squad-calls/squads/{squad_id}/call-stats
Get call statistics for a squad.
Returns total calls and breakdown by agent for the specified date.
# Route Inbound Call To Squad
Source: https://docs.mrassistant.ai/api-reference/squad-calls/route-inbound-call-to-squad
https://api.mrassistant.ai/openapi.json post /squad-calls/squads/{squad_id}/route-inbound
Route an inbound call to a squad member.
This endpoint is typically called by LiveKit webhooks or SIP providers.
No authentication required for webhooks.
# Create Squad
Source: https://docs.mrassistant.ai/api-reference/squads/create-squad
https://api.mrassistant.ai/openapi.json post /squads
Create a new squad with intelligent routing.
Supports:
- Multiple agents with specialized roles
- Intelligent transfer rules (context-aware, sentiment-based)
- Warm transfers with conversation context
- Load balancing and skill-based routing
# Delete Squad
Source: https://docs.mrassistant.ai/api-reference/squads/delete-squad
https://api.mrassistant.ai/openapi.json delete /squads/{squad_id}
Delete a squad.
# Get Squad
Source: https://docs.mrassistant.ai/api-reference/squads/get-squad
https://api.mrassistant.ai/openapi.json get /squads/{squad_id}
Get a specific squad.
# Get Squad Agents
Source: https://docs.mrassistant.ai/api-reference/squads/get-squad-agents
https://api.mrassistant.ai/openapi.json get /squads/{squad_id}/agents
Get agents in a squad.
# Get Squad Analytics
Source: https://docs.mrassistant.ai/api-reference/squads/get-squad-analytics
https://api.mrassistant.ai/openapi.json get /squads/{squad_id}/analytics
Get Squad analytics and performance metrics.
Includes:
- Transfer statistics
- Member utilization
- Routing strategy performance
- Session distribution
# Get Squad Sessions
Source: https://docs.mrassistant.ai/api-reference/squads/get-squad-sessions
https://api.mrassistant.ai/openapi.json get /squads/{squad_id}/sessions
Get active and recent Squad sessions.
Shows conversation sessions being handled by Squad members.
# List Squads
Source: https://docs.mrassistant.ai/api-reference/squads/list-squads
https://api.mrassistant.ai/openapi.json get /squads
List squads for the current tenant.
# Reload Squad Cache
Source: https://docs.mrassistant.ai/api-reference/squads/reload-squad-cache
https://api.mrassistant.ai/openapi.json post /squads/{squad_id}/reload
Reload Squad configuration in all agent caches.
Use this after updating Squad members or routing rules
to ensure active agents pick up changes.
# Transfer To Squad
Source: https://docs.mrassistant.ai/api-reference/squads/transfer-to-squad
https://api.mrassistant.ai/openapi.json post /squads/{squad_id}/transfer
Transfer a call to a squad member with intelligent routing.
Supports:
- Context-aware routing
- Sentiment-based routing
- Keyword/intent-based routing
- Warm transfers with conversation summary
- Load balancing
- Skill matching
# Update Squad
Source: https://docs.mrassistant.ai/api-reference/squads/update-squad
https://api.mrassistant.ai/openapi.json put /squads/{squad_id}
Update a squad with intelligent routing configuration.
# Serve Call Recording
Source: https://docs.mrassistant.ai/api-reference/storage/serve-call-recording
https://api.mrassistant.ai/openapi.json get /storage/call-recordings/{path}
Serve call recording files from MinIO (AUTHENTICATED).
This endpoint requires authentication and verifies the user has access
to the recording based on tenant ownership.
Path format: /storage/call-recordings/{tenant_id}/calls/{call_id}/{filename}
Example: /storage/call-recordings/8a18c5c3-f449-46ae-bb71-5e813b0ebb44/calls/67403062-3f47-45cb-9f6b-cd92c07c92bc/recording.mp4
# Serve Storage File
Source: https://docs.mrassistant.ai/api-reference/storage/serve-storage-file
https://api.mrassistant.ai/openapi.json get /storage/{bucket}/{path}
Generic endpoint to serve files from any MinIO bucket.
This endpoint can be used to serve files from any bucket, but voice-previews
and call-recordings should use the dedicated endpoints above.
Path format: /storage/{bucket}/{path}
# Serve Voice Preview
Source: https://docs.mrassistant.ai/api-reference/storage/serve-voice-preview
https://api.mrassistant.ai/openapi.json get /storage/voice-previews/{provider}/{voice_id}/{filename}
Serve voice preview files from MinIO.
This endpoint proxies requests to MinIO, allowing frontend applications
to access voice previews without direct MinIO access.
Path format: /storage/voice-previews/{provider}/{voice_id}/{filename}
Example: /storage/voice-previews/openai/coral/preview.mp3
# Check Deployment Readiness
Source: https://docs.mrassistant.ai/api-reference/system/check-deployment-readiness
https://api.mrassistant.ai/openapi.json get /system/deployment/readiness
Check if system is ready for production deployment.
# Comprehensive Health Check
Source: https://docs.mrassistant.ai/api-reference/system/comprehensive-health-check
https://api.mrassistant.ai/openapi.json get /system/health/comprehensive
Comprehensive health check for all system components.
# Get Configuration Summary
Source: https://docs.mrassistant.ai/api-reference/system/get-configuration-summary
https://api.mrassistant.ai/openapi.json get /system/configuration/summary
Get complete system configuration summary.
# Get Services Health
Source: https://docs.mrassistant.ai/api-reference/system/get-services-health
https://api.mrassistant.ai/openapi.json get /system/services/health
Get health status of all external services.
# Get Services Registry
Source: https://docs.mrassistant.ai/api-reference/system/get-services-registry
https://api.mrassistant.ai/openapi.json get /system/services/registry
Get information about all registered services.
# Validate Api Completeness
Source: https://docs.mrassistant.ai/api-reference/system/validate-api-completeness
https://api.mrassistant.ai/openapi.json get /system/api/validation
Validate that all required APIs are available and properly configured.
# Validate System Features
Source: https://docs.mrassistant.ai/api-reference/system/validate-system-features
https://api.mrassistant.ai/openapi.json get /system/features/validation
Validate all system features and integrations.
# Validate User Flows
Source: https://docs.mrassistant.ai/api-reference/system/validate-user-flows
https://api.mrassistant.ai/openapi.json get /system/user-flows/validation
Validate that all user flows are properly implemented.
# Create Tenant
Source: https://docs.mrassistant.ai/api-reference/tenants/create-tenant
https://api.mrassistant.ai/openapi.json post /tenants
Create a new tenant (organization/customer) - Usually auto-created during signup.
**⚠️ NOTE: For most users, tenants are AUTO-CREATED during signup!**
**When to use this endpoint:**
- **Platform Admins**: Manually create organizations for customers
- **Recovery**: If auto-creation failed during signup
- **Migration**: Importing existing organizations into the platform
- **Advanced**: Creating additional sub-organizations
**For Regular Users (BUSINESS role):**
- Your tenant is **automatically created** when you sign up via `POST /auth/signup`
- You don't need to call this endpoint
- Your tenant_id = your owner_id (automatically linked)
**What it does:**
- Creates a new tenant account with unique ID (uses current_user.owner_id)
- Sets up billing plan and usage limits
- Configures SIP capabilities (if enabled)
- Establishes compliance settings (HIPAA, PCI)
- Encrypts sensitive credentials (SIP passwords)
**Key Configuration:**
- `name`: Organization name
- `billing_plan`: Subscription tier (starter/business/enterprise)
- `max_concurrent_calls`: Call capacity limit (1-1000)
- `monthly_call_limit`: Monthly usage cap
- `sip_enabled`: Enable phone number integration
- `recording_enabled`: Call recording capability
- `analytics_enabled`: Analytics dashboard access
**User Flow Clarification:**
1. **Sign up** → `POST /auth/signup` (role=BUSINESS) → Tenant auto-created ✅
2. **Login** → `POST /auth/token` → Get access token
3. **Create agents** → `POST /agents` → Start building
❌ You do NOT need to manually create tenant after signup!
# Delete Tenant
Source: https://docs.mrassistant.ai/api-reference/tenants/delete-tenant
https://api.mrassistant.ai/openapi.json delete /tenants/{tenant_id}
Delete tenant from the platform (PERMANENT).
**Purpose:** Remove a tenant/organization from the platform
**What it does:**
- Permanently deletes tenant account
- Used when customer cancels service
- Removes all tenant data from the system
**⚠️ WARNING - CASCADE DELETE:**
This operation permanently deletes ALL related data:
- **All agents** created by this tenant
- **Call history and recordings** (all calls)
- **Workflows and integrations** (custom flows, API configs)
- **Files and logs** (knowledge base, activity logs)
- **SIP trunks** (phone number configurations)
- **Squad configurations** (agent teams)
**Use Cases:**
- Customer account cancellation
- Service termination
- Data cleanup after trial expiration
**Recommended Practice:**
- Export/backup tenant data before deletion
- Verify tenant has no active calls/sessions
- Notify customer before deletion
- Consider soft-delete (status=inactive) instead
# Get Tenant
Source: https://docs.mrassistant.ai/api-reference/tenants/get-tenant
https://api.mrassistant.ai/openapi.json get /tenants/{tenant_id}
Get detailed information about a specific tenant.
**Purpose:** Retrieve complete tenant profile and configuration
**What it does:**
- Returns complete tenant profile
- Shows billing, usage, and configuration details
- Displays SIP settings and compliance status
- Shows webhook configuration for integrations
**Response Includes:**
- Organization details (name, status, created_at)
- Billing plan and usage limits
- Feature flags (sip_enabled, recording_enabled, analytics_enabled)
- Compliance settings (hipaa_enabled, pci_enabled)
- Recording format and retention policy (retention_days)
- Webhook URL for event notifications
- Monthly usage tracking (monthly_usage_cents)
- Creation and update timestamps
**Use Cases:**
- Viewing customer account details
- Auditing tenant configuration
- Billing and usage review
- Support and troubleshooting
# Get Tenant Stats
Source: https://docs.mrassistant.ai/api-reference/tenants/get-tenant-stats
https://api.mrassistant.ai/openapi.json get /tenants/{tenant_id}/stats
Get tenant usage statistics and analytics.
**Purpose:** View usage statistics, performance metrics, and billing data
**What it returns:**
```json
{
"tenant_id": "uuid",
"total_agents": 5, // Number of AI agents created
"total_calls_today": 23, // Today's call volume
"total_calls_month": 456, // Monthly call volume
"avg_call_duration": 180.5, // Average call length (seconds)
"avg_sentiment_score": 0.75, // Customer satisfaction (-1 to 1)
"active_sessions": 3, // Current active calls/sessions
"monthly_usage_cents": 1250, // Billing amount for current month
"last_call_at": "2025-10-02T10:30:00Z" // Last call timestamp
}
```
**Used For:**
- **Billing calculations:** Track monthly_usage_cents for invoicing
- **Usage monitoring:** Check if approaching monthly_call_limit
- **Customer dashboards:** Display usage stats to tenant users
- **Capacity planning:** Monitor concurrent calls vs max_concurrent_calls
- **Performance tracking:** Average call duration and sentiment scores
- **Support insights:** Identify usage patterns and issues
**Real-World Scenarios:**
- Admin sees tenant approaching limit → proactively offer upgrade
- Customer views their dashboard → sees call volume trends
- Billing system queries stats → generates monthly invoice
- Support team checks stats → troubleshoots customer issues
# List Tenants
Source: https://docs.mrassistant.ai/api-reference/tenants/list-tenants
https://api.mrassistant.ai/openapi.json get /tenants
List all tenants (for platform administrators).
**Purpose:** View all tenants/organizations on the platform
**What it does:**
- Returns paginated list of all organizations
- Supports filtering by status (active/inactive)
- Used by platform admins to manage customers
- Shows tenant overview for monitoring
**Parameters:**
- `limit`: Maximum number of tenants to return (default: 100)
- `offset`: Number of tenants to skip for pagination (default: 0)
- `status_filter`: Filter by tenant status (active/inactive/suspended)
**Use Cases:**
- Platform administration and monitoring
- Customer account management
- Bulk operations on tenants
- Usage reporting across all customers
# Update Tenant
Source: https://docs.mrassistant.ai/api-reference/tenants/update-tenant
https://api.mrassistant.ai/openapi.json put /tenants/{tenant_id}
Update tenant settings and configuration.
**Purpose:** Complete your organization setup or modify settings
**👤 For Business Users After Signup:**
After signing up, your tenant is auto-created with minimal fields (just name).
Use this endpoint to complete your organization setup:
- Set your organization name properly
- Configure billing plan (starter/business/enterprise)
- Set usage limits (max_concurrent_calls, monthly_call_limit)
- Enable features (SIP, recording, analytics)
- Configure compliance (HIPAA, PCI for healthcare/finance)
**What it does:**
- Update organization name and billing plan
- Adjust usage limits and concurrent call capacity
- Enable/disable features (SIP, recording, analytics)
- Change compliance settings (HIPAA, PCI)
- Update SIP credentials (automatically encrypted)
- Modify webhook configuration for integrations
**Common Use Cases:**
- **Initial Setup:** After signup, set your org name and billing plan
- **Upgrade subscription:** Change billing_plan, increase limits
- **Enable phone calls:** Set sip_enabled=true, configure SIP details
- **Enable enterprise features:** Set hipaa_enabled=true, pci_enabled=true
- **Update webhook:** Change webhook_url for event notifications
**Your tenant_id = your owner_id** (returned in login token)
**Security Notes:**
- SIP passwords are automatically encrypted before storage
- Webhook secrets are stored securely
- All changes are logged for audit trail
# Check Tool Integration
Source: https://docs.mrassistant.ai/api-reference/testing/check-tool-integration
https://api.mrassistant.ai/openapi.json get /testing/tools/integration-check
Comprehensive integration check for all tools with LiveKit Cloud and External Agent Factory.
This endpoint verifies:
1. Tool configuration is properly structured for external agent factory
2. LiveKit-dependent tools (DTMF, Handoff) have correct parameters
3. API keys are properly configured
4. JSON payload format matches external agent factory expectations
Returns detailed report on integration readiness.
# List All Tools
Source: https://docs.mrassistant.ai/api-reference/testing/list-all-tools
https://api.mrassistant.ai/openapi.json get /testing/tools/registry/list
List all available tools in the registry with their configurations.
Note: This endpoint does not require authentication for testing purposes.
# Seed Tools
Source: https://docs.mrassistant.ai/api-reference/testing/seed-tools
https://api.mrassistant.ai/openapi.json post /testing/tools/registry/seed
Seed the tool registry with all 14 default agent tools.
This endpoint populates the database with the standard set of tools.
Note: This endpoint does not require authentication for testing purposes.
# Simulate Session
Source: https://docs.mrassistant.ai/api-reference/testing/simulate-session
https://api.mrassistant.ai/openapi.json post /testing/sessions/simulate
Simulate a conversation session for testing.
Simulates user inputs and agent responses without actually
creating a live session.
# Test All Tools
Source: https://docs.mrassistant.ai/api-reference/testing/test-all-tools
https://api.mrassistant.ai/openapi.json get /testing/tools/test-all
Test all agent tools to verify they are working correctly.
This endpoint runs non-destructive tests on all available tools
to ensure they can be executed properly by agents.
Note: This endpoint does not require authentication for testing purposes.
# Test Single Tool
Source: https://docs.mrassistant.ai/api-reference/testing/test-single-tool
https://api.mrassistant.ai/openapi.json post /testing/tools/{tool_key}/test
Test a single tool with custom arguments.
This allows testing specific tools with custom parameters
to validate their functionality.
Note: This endpoint does not require authentication for testing purposes.
# Validate Agent
Source: https://docs.mrassistant.ai/api-reference/testing/validate-agent
https://api.mrassistant.ai/openapi.json post /testing/agents/{agent_id}/validate
Validate an agent configuration.
Checks:
- Agent exists and is accessible
- Required configuration fields
- Tool configurations
- Workflow assignments
- Provider settings
# Validate Workflow
Source: https://docs.mrassistant.ai/api-reference/testing/validate-workflow
https://api.mrassistant.ai/openapi.json post /testing/workflows/validate
Validate a workflow configuration before saving.
Checks:
- Node structure and types
- Edge connections
- Required fields
- Tool availability
- Circular dependencies
# Add Tool To Agent
Source: https://docs.mrassistant.ai/api-reference/tools/add-tool-to-agent
https://api.mrassistant.ai/openapi.json post /tools/agents/{agent_id}/add-tool
Add and configure a tool for a specific agent.
**Multi-Level Configuration:**
- **Tenant Level**: API keys, OAuth tokens (shared across all agents)
- **Agent Level**: Tool-specific settings (different per agent)
**How It Works:**
1. Tool connection created at tenant level (if needed)
2. Agent-specific configuration stored separately
3. Different agents can use same tool with different configs
**Example: Google Sheets Tool**
```json
{
"tool_key": "google_sheets_tool",
"enabled": true,
"config": {
"access_token": "ya29.xxx", // Tenant level (shared)
"refresh_token": "1//xxx", // Tenant level (shared)
"spreadsheetId": "1BxiMVxxx", // Agent level (unique per agent)
"range": "Sheet1!A:Z" // Agent level (unique per agent)
}
}
```
**Example: Slack Tool**
```json
{
"tool_key": "slack_send_message_tool",
"enabled": true,
"config": {
"bot_token": "xoxb-xxx", // Tenant level (shared)
"channel": "#agent1-notifications" // Agent level (unique per agent)
}
}
```
**Result:**
- Agent 1 can log to "Sheet1" with "#support" channel
- Agent 2 can log to "Sheet2" with "#sales" channel
- Both use same tenant OAuth token
# Configure Tool
Source: https://docs.mrassistant.ai/api-reference/tools/configure-tool
https://api.mrassistant.ai/openapi.json post /tools/{tool_key}/configure
Configure tool-specific parameters (Google Sheets spreadsheet ID, Slack channel, etc.).
This creates a user-level tool connection with configuration.
# Confirm Tool Execution
Source: https://docs.mrassistant.ai/api-reference/tools/confirm-tool-execution
https://api.mrassistant.ai/openapi.json post /tools/executions/{execution_id}/confirm
Confirm or reject a tool execution that requires user approval.
# Connect Tool
Source: https://docs.mrassistant.ai/api-reference/tools/connect-tool
https://api.mrassistant.ai/openapi.json post /tools/connections/{tool_key}
Connect a tool for the current user.
# Create Custom Tool
Source: https://docs.mrassistant.ai/api-reference/tools/create-custom-tool
https://api.mrassistant.ai/openapi.json post /tools/custom
Create or update custom tool with upsert logic.
# Disconnect Tool
Source: https://docs.mrassistant.ai/api-reference/tools/disconnect-tool
https://api.mrassistant.ai/openapi.json delete /tools/connections/{tool_key}
Disconnect a tool for the current user.
# Execute Tool
Source: https://docs.mrassistant.ai/api-reference/tools/execute-tool
https://api.mrassistant.ai/openapi.json post /tools/execute
Execute a tool.
# Get Execution Status
Source: https://docs.mrassistant.ai/api-reference/tools/get-execution-status
https://api.mrassistant.ai/openapi.json get /tools/executions/{execution_id}
Get tool execution status.
# Get Tool Config
Source: https://docs.mrassistant.ai/api-reference/tools/get-tool-config
https://api.mrassistant.ai/openapi.json get /tools/{tool_key}/config
Get current tool configuration for the user.
Returns configured values (with sensitive fields masked).
# Get Tool Requirements
Source: https://docs.mrassistant.ai/api-reference/tools/get-tool-requirements
https://api.mrassistant.ai/openapi.json get /tools/{tool_key}/requirements
Get full configuration requirements for a tool.
This is intended for frontend use to guide users through:
- Tenant-level setup (API keys / OAuth tokens)
- Agent-level setup (per-agent settings)
Response includes:
- Registry metadata (display_name, requires_connection, scopes, ui_manifest)
- Configuration guide from ToolConfigurationService:
- tenant vs agent required/optional fields
- auth_type
- example configuration payload
- setup notes
# Get Tool Schema
Source: https://docs.mrassistant.ai/api-reference/tools/get-tool-schema
https://api.mrassistant.ai/openapi.json get /tools/{tool_key}/schema
Get tool configuration schema for frontend forms.
Returns field definitions, types, validation rules.
# List Available Tools
Source: https://docs.mrassistant.ai/api-reference/tools/list-available-tools
https://api.mrassistant.ai/openapi.json get /tools/registry
List all available tools in registry.
# Retry Execution
Source: https://docs.mrassistant.ai/api-reference/tools/retry-execution
https://api.mrassistant.ai/openapi.json post /tools/executions/{execution_id}/retry
Retry a failed tool execution.
# Create Transfer Target
Source: https://docs.mrassistant.ai/api-reference/transfer-targets/create-transfer-target
https://api.mrassistant.ai/openapi.json post /transfer-targets
# Delete Transfer Target
Source: https://docs.mrassistant.ai/api-reference/transfer-targets/delete-transfer-target
https://api.mrassistant.ai/openapi.json delete /transfer-targets/{target_id}
# Get Transfer Target
Source: https://docs.mrassistant.ai/api-reference/transfer-targets/get-transfer-target
https://api.mrassistant.ai/openapi.json get /transfer-targets/{target_id}
# List Transfer Targets
Source: https://docs.mrassistant.ai/api-reference/transfer-targets/list-transfer-targets
https://api.mrassistant.ai/openapi.json get /transfer-targets
# Update Transfer Target
Source: https://docs.mrassistant.ai/api-reference/transfer-targets/update-transfer-target
https://api.mrassistant.ai/openapi.json patch /transfer-targets/{target_id}
# Associate Workflow
Source: https://docs.mrassistant.ai/api-reference/unified-agent-config/associate-workflow
https://api.mrassistant.ai/openapi.json post /unified/agents/{agent_id}/workflow
Associate a workflow with an agent.
Validation checks:
- Agent exists and user owns it
- Workflow exists and user owns it
- Workflow belongs to same tenant as agent
- Workflow is active (not archived)
- Workflow tools are available to agent (optional)
# Disassociate Workflow
Source: https://docs.mrassistant.ai/api-reference/unified-agent-config/disassociate-workflow
https://api.mrassistant.ai/openapi.json delete /unified/agents/{agent_id}/workflow
Disassociate workflow from an agent.
# Get Agent Configuration
Source: https://docs.mrassistant.ai/api-reference/unified-agent-config/get-agent-configuration
https://api.mrassistant.ai/openapi.json get /unified/agents/{agent_id}/config
Get comprehensive agent configuration.
# Update Agent Configuration
Source: https://docs.mrassistant.ai/api-reference/unified-agent-config/update-agent-configuration
https://api.mrassistant.ai/openapi.json put /unified/agents/{agent_id}/config
Update comprehensive agent configuration.
# Update Agent Tools
Source: https://docs.mrassistant.ai/api-reference/unified-agent-config/update-agent-tools
https://api.mrassistant.ai/openapi.json post /unified/agents/{agent_id}/tools
Update agent tools configuration.
# Get Integration Status
Source: https://docs.mrassistant.ai/api-reference/voice-services/get-integration-status
https://api.mrassistant.ai/openapi.json get /voice-services/integration-status
Get status of provider integrations (for platform owner monitoring).
# Get Livekit Integration Status
Source: https://docs.mrassistant.ai/api-reference/voice-services/get-livekit-integration-status
https://api.mrassistant.ai/openapi.json get /voice-services/livekit-integration
Get detailed LiveKit integration status.
# Get Livekit Regions
Source: https://docs.mrassistant.ai/api-reference/voice-services/get-livekit-regions
https://api.mrassistant.ai/openapi.json get /voice-services/livekit/regions
Get available LiveKit Cloud regions.
This endpoint proxies the LiveKit Cloud API to retrieve available regions.
The frontend cannot access LiveKit Cloud APIs directly due to authentication requirements.
# Get Provider Recommendations For Language
Source: https://docs.mrassistant.ai/api-reference/voice-services/get-provider-recommendations-for-language
https://api.mrassistant.ai/openapi.json get /voice-services/provider-recommendations
Get provider recommendations for a specific language and use case.
# Create Voice Token
Source: https://docs.mrassistant.ai/api-reference/voice/create-voice-token
https://api.mrassistant.ai/openapi.json post /voice/tokens
Create LiveKit token for voice session.
# End Voice Session
Source: https://docs.mrassistant.ai/api-reference/voice/end-voice-session
https://api.mrassistant.ai/openapi.json post /voice/sessions/{session_id}/end
End a voice session.
# Get Livekit Regions
Source: https://docs.mrassistant.ai/api-reference/voice/get-livekit-regions
https://api.mrassistant.ai/openapi.json get /voice/livekit/regions
Get available LiveKit Cloud regions for web calls.
This endpoint proxies the LiveKit Cloud API to retrieve available regions.
Use this during web call setup to:
- Display available regions to users
- Configure which LiveKit region to use for WebRTC connections
- Optimize latency by selecting the closest region
**Frontend Usage:**
Instead of calling LiveKit Cloud directly (which requires API keys), use this endpoint:
```
GET /api/v1/voice/livekit/regions
```
**Response:** Returns LiveKit Cloud regions data including region codes, names, and endpoints.
# Get Session State
Source: https://docs.mrassistant.ai/api-reference/voice/get-session-state
https://api.mrassistant.ai/openapi.json get /voice/sessions/{session_id}/state
Get current session state with tool results.
# Get Session Trace
Source: https://docs.mrassistant.ai/api-reference/voice/get-session-trace
https://api.mrassistant.ai/openapi.json get /voice/sessions/{session_id}/trace
Get diagnostic trace for a voice session (audio→ASR→LLM→TTS pipeline).
# Run Agent Turn
Source: https://docs.mrassistant.ai/api-reference/voice/run-agent-turn
https://api.mrassistant.ai/openapi.json post /voice/agents/run
Run an agent turn (internal endpoint for orchestrator).
# Session Events Sse
Source: https://docs.mrassistant.ai/api-reference/voice/session-events-sse
https://api.mrassistant.ai/openapi.json get /voice/sessions/{session_id}/events
Server-Sent Events (SSE) endpoint for real-time session updates.
Provides live updates for:
- transcript.partial: Partial transcription results
- transcript.final: Final transcription results
- tool.confirm: Tool confirmation requests
- tool.result: Tool execution results
- session.ended: Session termination
- language.detected: Language detection events
- agent.thinking: Agent processing indicator
- agent.speaking: Agent voice output
# Start Voice Session
Source: https://docs.mrassistant.ai/api-reference/voice/start-voice-session
https://api.mrassistant.ai/openapi.json post /voice/sessions/{session_id}/start
Start a voice session.
# Attach Tool To Node
Source: https://docs.mrassistant.ai/api-reference/workflows/attach-tool-to-node
https://api.mrassistant.ai/openapi.json post /workflows/{workflow_id}/nodes/{node_id}/tools
Attach a CONFIGURED tool *instance* to a workflow node.
Workflow nodes never reference tool *types* (registry keys) directly —
they only reference instances that already exist in `agent_tools`. The
rule: a user cannot attach `cold_transfer` to a node; they must first
create a configured instance like `transfer_to_billing` (with its
sip_trunk_id, target_number, etc.) on an agent, then attach that
instance_name here.
Validation:
- If `?agent_id=` is provided, the (agent_id, instance_name) pair
MUST exist in `agent_tools` (active + enabled). Strict.
- Otherwise, the instance_name MUST exist on at least one agent
currently using this workflow (i.e. `agents.workflow_id == this`).
- If the workflow is not yet attached to any agent, the request is
rejected with 422 — bind the workflow to an agent first, then
attach instances. (Avoids accumulating dangling string refs that
only fail at runtime.)
# Create Workflow
Source: https://docs.mrassistant.ai/api-reference/workflows/create-workflow
https://api.mrassistant.ai/openapi.json post /workflows
Create a new workflow for agent conversation flow.
# Delete Workflow
Source: https://docs.mrassistant.ai/api-reference/workflows/delete-workflow
https://api.mrassistant.ai/openapi.json delete /workflows/{workflow_id}
Delete a workflow with validation.
Args:
workflow_id: Workflow to delete
force: If True, removes workflow from all agents before deleting
Behavior:
- If no agents using workflow: Deletes immediately
- If agents using workflow and force=False: Returns error with agent list
- If agents using workflow and force=True: Removes from agents then deletes
# Detach Tool From Node
Source: https://docs.mrassistant.ai/api-reference/workflows/detach-tool-from-node
https://api.mrassistant.ai/openapi.json delete /workflows/{workflow_id}/nodes/{node_id}/tools/{instance_name}
Detach a tool instance from a workflow node.
# Download Workflow Json
Source: https://docs.mrassistant.ai/api-reference/workflows/download-workflow-json
https://api.mrassistant.ai/openapi.json get /workflows/{workflow_id}/download-json
Download workflow JSON file.
# Export Workflow Json
Source: https://docs.mrassistant.ai/api-reference/workflows/export-workflow-json
https://api.mrassistant.ai/openapi.json get /workflows/{workflow_id}/export-json
Export workflow as JSON.
# Get Workflow
Source: https://docs.mrassistant.ai/api-reference/workflows/get-workflow
https://api.mrassistant.ai/openapi.json get /workflows/{workflow_id}
Get a specific workflow.
# Import Workflow Json
Source: https://docs.mrassistant.ai/api-reference/workflows/import-workflow-json
https://api.mrassistant.ai/openapi.json post /workflows/import-json
Import workflow from JSON.
# List Node Tool Attachments
Source: https://docs.mrassistant.ai/api-reference/workflows/list-node-tool-attachments
https://api.mrassistant.ai/openapi.json get /workflows/{workflow_id}/nodes/{node_id}/tools
List the `agent_tools` instance attachments on a workflow node.
# List Workflows
Source: https://docs.mrassistant.ai/api-reference/workflows/list-workflows
https://api.mrassistant.ai/openapi.json get /workflows
List workflows for the current user.
# Update Workflow
Source: https://docs.mrassistant.ai/api-reference/workflows/update-workflow
https://api.mrassistant.ai/openapi.json put /workflows/{workflow_id}
Update a workflow.
# Validate Workflow
Source: https://docs.mrassistant.ai/api-reference/workflows/validate-workflow
https://api.mrassistant.ai/openapi.json post /workflows/{workflow_id}/validate
Validate workflow structure and node connections.
# MCP and B2C businesses
Source: https://docs.mrassistant.ai/get-started/mcp-for-b2c
Why a Model Context Protocol layer matters when you serve consumers at scale
Consumer-facing brands move fast: support chats, voice assistants, and self-serve flows all need **reliable access** to the same systems your team uses—orders, appointments, inventory, policies—without turning every integration into a custom one-off.
## What MCP gives you at a high level
The **Model Context Protocol (MCP)** is a way to expose **tools and data** to AI clients through a well-defined server interface. Think of it as a **stable boundary** between your assistants (and the models behind them) and the actions they are allowed to take.
For documentation purposes, you do not need implementation details here. What matters is the **role** MCP plays in your architecture.
## Why B2C companies especially benefit
**1. One controlled surface for many channels**\
You may offer help on the web, in app, over voice, and inside third-party copilots. An MCP-oriented setup lets you **reuse the same capabilities** across those surfaces instead of re-implementing each integration per channel.
**2. Clear limits for customer-facing AI**\
B2C traffic is high variance: edge cases, misunderstandings, and abuse attempts are normal. A dedicated MCP layer helps you **define what is callable**, with room for your own review, logging, and rate limits—without baking business rules into every prompt.
**3. Faster iteration on “what the assistant can do”**\
Product and operations teams often want new actions (“check order status,” “book a slot,” “explain this policy”). Exposing those as **versioned tools** behind an MCP server keeps changes **predictable** for engineering and safer for customers.
**4. Separation of concerns**\
Your voice or chat product can focus on **conversation quality** and **multilingual experience**, while your MCP server focuses on **talking to internal systems** in a way that matches your security and compliance posture.
## When an MCP server is worth prioritizing
* You already have (or plan) **multiple AI touchpoints** that need the same business actions.
* You want **governance** over which tools exist and how they are documented for internal and partner use.
* You prefer **not** duplicating integration logic inside every assistant configuration.
## How this relates to MrAssistant AI
MrAssistant AI is aimed at **multilingual voice and agent** experiences. In a typical B2C setup, the assistant handles dialogue and realtime behavior, while **structured actions**—lookups, bookings, escalations—flow through the integrations your organization controls. Positioning an **MCP server** in that path is a common pattern for teams that want consumer-grade scale without losing control of the backend.
## Next steps
# Web and voice
Source: https://docs.mrassistant.ai/get-started/web-and-voice
How customer surfaces and realtime voice fit together
MrAssistant AI is built around **realtime, conversational** experiences. In most B2C setups, the customer interacts through your **app or website**, while your services coordinate **sessions**, **agent configuration**, and **downstream integrations**.
## Mental model
1. **Configuration** — You define how the assistant should sound, which languages apply, and which high-level capabilities are in scope.
2. **Sessions** — A session is the unit of a customer attempt: one guided flow or conversation.
3. **Media path** — Audio and timing depend on the **realtime stack** you connect; treat that as a product decision alongside UX and support.
## Web and mobile clients
Keep **business rules and integration logic** on systems you operate, not embedded in static client bundles. Clients should focus on **capture, playback, and UX**, while your backend decides what the assistant may do next.
## Regional and reliability planning
Voice is sensitive to **latency** and **distance**. When you move from pilot to production, plan for **where traffic runs** and how you observe quality (drops, silence, user retries).
## Next steps
# Introduction
Source: https://docs.mrassistant.ai/index
Multilingual voice agents and a practical integration model for consumer brands
MrAssistant AI helps teams ship **multilingual voice and agent** experiences for **business-to-consumer** use cases: self-serve help, guided flows, and handoffs to human teams when needed.
These docs stay **high level**: how the product fits together, what to plan for on the voice side, and why many B2C teams adopt an **MCP-style integration layer** so assistants stay maintainable as you add channels and capabilities.
## Get started
A simple mental model for going from idea to integrated experience.
Why a Model Context Protocol server matters for consumer-facing AI at scale.
How web, mobile, and realtime voice pieces fit together.
Technical reference generated from the public API description.
## Build
What an agent represents and how you evolve it over time.
Grounding content and extending behavior with controlled actions.
Speech, language models, and provider choice at a glance.
Serving more than one language and locale with confidence.
For machine-readable API details, your team can use the published **OpenAPI** document linked from the site header when that fits your workflow.
# Quickstart
Source: https://docs.mrassistant.ai/quickstart
A high-level path from concept to integrated MrAssistant experience
This quickstart is **conceptual**: it describes the order of decisions most teams make. For field-level request shapes, use the **API reference** when your team is ready for implementation detail.
## 1. Clarify the consumer journey
Decide what the customer should accomplish in one session: get an answer, complete a task, or reach a human. That drives how you structure **agents**, **languages**, and **handoffs**.
## 2. Align voice and channels
Choose where the experience lives first (web, app, phone, or a mix). Realtime voice usually involves **coordination** between your product surface and your backend; see [Web and voice](/get-started/web-and-voice).
## 3. Plan integrations deliberately
For B2C scale, teams often introduce a **small set of well-defined actions** (lookups, bookings, tickets) behind a stable interface rather than growing ad hoc scripts inside prompts. [MCP for B2C](/get-started/mcp-for-b2c) explains why that pattern is common.
## 4. Configure agents at a high level
Think in terms of **instructions**, **languages**, **voice persona**, and **what the assistant is allowed to do**. Iterate with real callers and transcripts rather than only desktop testing.
## 5. Roll out in phases
Pilot with a narrow audience, measure containment and satisfaction, then widen traffic. Keep operational playbooks (escalation, content updates, incident response) next to the technical rollout.
## Next steps
# Multilingual
Source: https://docs.mrassistant.ai/voice/multilingual
Languages, voices, and cross-locale behavior
MrAssistant AI targets **multilingual** experiences: callers may start in one language and switch to another, or require locale-specific voices and ASR models.
## Language matrix
The API exposes **supported languages** and a **matrix** that helps you pair STT, TTS, and LLM capabilities. Start from the matrix when you design a new agent.
## Voices
List voices per provider, search catalogs when available, and align **voice options** with your brand and accessibility goals.
## Conversation behavior
* Prefer **explicit language confirmation** when ambiguity is costly (for example finance or healthcare).
* Keep **fallback** providers configured where the API supports it, so a single provider outage does not drop the call.
## Related
# Voice and providers
Source: https://docs.mrassistant.ai/voice/providers
Speech, models, and choosing a stack that fits your customers
MrAssistant connects **speech recognition**, **speech synthesis**, and **language models** through a provider model. Product teams care about **latency**, **accent coverage**, and **cost**; engineering teams care about **compatibility** and **rollout**.
## Speech to text
Choose transcribers that match your **languages** and **noise environments**. Retail, mobility, and support lines often have very different acoustic profiles.
## Text to speech
Pick voices that fit **brand** and **clarity**. Multilingual products may need **per-locale** voices rather than a single default.
## Language models
Balance **quality**, **speed**, and **cost**. Voice conversations reward models that behave well under **short user turns** and **interruptions**.
## Recommended defaults
When you are unsure where to start, use any **recommended configuration** your deployment exposes, then tune with real callers rather than only synthetic tests.
## Related