Getting Started
REST API Integration
Complete guide to integrating MuChat AI Agents using the MuChat API v2 for custom integrations and applications.
Overview
The MuChat REST API enables you to integrate AI-powered conversations into any application or workflow. Build custom chat experiences, automate customer interactions, and manage your AI agents programmatically.
API v2 features structured error codes, cursor-based pagination, and real-time streaming via Server-Sent Events (SSE).
Base URL:
https://api.mu.chat/api/v2Send Messages
Chat with your AI agents and handle real-time streaming responses
Manage AI Agents
Create, configure, and update AI agents and their training sources
Access Data
Retrieve conversations and messages from your AI interactions
Quick Start
Get Your API Key
- Visit your MuChat Dashboard
- Go to Workspace settings → API keys
- Click Create API Key and copy the generated key
Get Your Agent ID
- Select your AI Agent in the dashboard
- Go to Settings → General
- Copy the Agent ID from the Agent details card
Send Your First Message
Test your integration with a simple chat request:
curl -X POST 'https://api.mu.chat/api/v2/agents/YOUR_AGENT_ID/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "Hello! How can you help me?",
"stream": false
}'Expected Response:
{
"data": {
"id": "msg_abc123",
"role": "assistant",
"parts": [
{ "type": "text", "text": "Hello! I'm here to help answer your questions and assist with any information you need. What can I help you with today?" }
],
"metadata": {
"userMessageId": "msg_xyz789",
"conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"userId": null,
"finishReason": "stop",
"usage": { "credits": 2 }
}
}
}Continue the Conversation
Conversation history is stored by MuChat — you don't need to resend previous messages. Pass the conversationId from the previous response to send a follow-up:
curl -X POST 'https://api.mu.chat/api/v2/agents/YOUR_AGENT_ID/chat' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"message": "Tell me more about your pricing.",
"conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stream": false
}'To associate a new conversation with one of your users, pass a userId on the first message. See User Conversations for details.
Chat API Streaming
The chat API streams responses in real time using Server-Sent Events. Each event is a data: line containing a JSON object with a type field, and the stream ends with data: [DONE]. Concatenate the text-delta events to build the full reply, and read the conversationId from the finish event to continue the conversation.
// streamer.js (Node.js 18+)
const apiKey = '<Your-Secret-Key>'
const agentId = '<Your Agent ID>'
const apiUrl = `https://api.mu.chat/api/v2/agents/${agentId}/chat`
async function readAgentReply() {
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: '<Your query here>',
stream: true,
// conversationId: '<Conversation ID>', // omit to start a new conversation
}),
})
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''
let conversationId
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
const lines = buffer.split('\n')
buffer = lines.pop() // keep any incomplete line for the next chunk
for (const line of lines) {
if (!line.startsWith('data: ')) continue
const data = line.slice('data: '.length)
if (data === '[DONE]') continue
const event = JSON.parse(data)
switch (event.type) {
case 'text-delta':
process.stdout.write(event.delta)
break
case 'finish':
conversationId = event.messageMetadata.conversationId
break
case 'error':
console.error('\nStream error:', event.errorText)
break
}
}
}
console.log('\nConversation ID:', conversationId)
}
readAgentReply().catch((error) => console.log('Error:', error.message))## streamer.py
import json
import requests
api_key = '<Your-Secret-Key>'
agent_id = '<Your Agent ID>'
api_url = f'https://api.mu.chat/api/v2/agents/{agent_id}/chat'
def read_agent_reply():
try:
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
data = {
'message': '<Your query here>',
'stream': True,
# 'conversationId': '<Conversation ID>', # omit to start a new conversation
}
response = requests.post(api_url, json=data, headers=headers, stream=True)
response.raise_for_status()
conversation_id = None
for line in response.iter_lines(decode_unicode=True):
if not line or not line.startswith('data: '):
continue
payload = line[len('data: '):]
if payload == '[DONE]':
continue
event = json.loads(payload)
if event['type'] == 'text-delta':
print(event['delta'], end='', flush=True)
elif event['type'] == 'finish':
conversation_id = event['messageMetadata']['conversationId']
elif event['type'] == 'error':
print(f"\nStream error: {event['errorText']}")
print(f'\nConversation ID: {conversation_id}')
except requests.exceptions.RequestException as error:
print('Error:', error)
read_agent_reply()Error Handling
API v2 returns structured errors with a machine-readable code:
{
"error": {
"code": "RATE_LIMIT_TOO_MANY_REQUESTS",
"message": "Too many requests, please try again later"
}
}Every response includes an x-request-id header — include it when contacting support. See Error Handling for all error codes and Rate Limiting for limits and retry guidance.
Performance Best Practices
🚀 Try It Live!
Ready to see the magic in action? Dive straight into our interactive playground where you can test every API endpoint, experiment with real responses, and build your integration in real-time.
Key API Endpoints
Chat API
Send messages and receive AI responses with streaming support
AI Agent Management
Create, update, and configure AI agents programmatically
Conversations
Access chat history and conversation messages
Sources
Add and manage the training sources for your AI agents
API v2 Overview
Explore the full API v2 reference — authentication, streaming, client actions, pagination, and more