Getting Started

REST API Integration

Complete guide to integrating MuChat AI Agents using the MuChat API v2 for custom integrations and applications.

Standard Plan required. The MuChat API v2 is available starting from the Standard Plan. View pricing →

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/v2

Send 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

Creating API key in MuChat dashboard
  1. Visit your MuChat Dashboard
  2. Go to Workspace settings → API keys
  3. Click Create API Key and copy the generated key

Store your API key securely and never expose it in client-side code.

Get Your Agent ID

Finding Agent ID in MuChat settings
  1. Select your AI Agent in the dashboard
  2. Go to Settings → General
  3. 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 }
    }
  }
}

stream defaults to true in API v2. Set it to false to receive the complete message as a single JSON response.

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))

For the full list of stream events — including client action (tool call) events — see the Streaming guide.

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

Optimization Strategies:

  • Use streaming for chat responses to improve perceived performance
  • Reuse conversationId for follow-ups instead of starting new conversations
  • Cache AI agent responses when appropriate
  • Respect the Retry-After header when you receive a 429 response
  • Use cursor-based pagination when listing conversations, messages, or sources

🚀 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

API v2 Overview

Explore the full API v2 reference — authentication, streaming, client actions, pagination, and more

MuChat documentation

On this page