REST API for developers

The MagizAI REST API lets you send messages to a bot, read conversations, and manage knowledge from your own backend. It's a JSON API authenticated with a Bearer token.

Authentication

Create a token in Settings › API tokens (you can hold up to 20). Send it on every request:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

All endpoints are scoped to your company. The base path is /api/v1.

Send a message and get the reply

The main endpoint sends a visitor message to a bot and returns the AI's reply (non-streaming).

POST /api/v1/chatbots/{public_key}/messages

{
  "message": "Do you ship to Canada?",
  "visitor_id": "abc-123",
  "conversation_id": "optional-uuid-to-continue"
}

Response:

{
  "conversation_id": "…uuid…",
  "status": "bot",
  "reply": { "id": 42, "content": "Yes, we ship to Canada…",
             "model": "…", "tokens_in": 120, "tokens_out": 45 }
}

If a human has taken the chat over, reply is null with a note. Over the monthly message cap returns 429; a provider outage returns 502.

Other endpoints

• GET /api/v1/me — your user and company.
• GET /api/v1/chatbots — list your bots.
• GET /api/v1/chatbots/{key} — one bot's details.
• GET /api/v1/chatbots/{key}/conversations — paginated conversations.
• GET /api/v1/conversations/{id} — one conversation with its messages.
• POST /api/v1/chatbots/{key}/knowledge — add a knowledge source ({ title, content, type: text|qa }).

Live streaming

The REST message endpoint returns the full reply at once. For token-by-token streaming like the widget, use the widget's SSE endpoint POST /widget/{key}/stream.

Partner portal API

Resellers embedding a client dashboard can use the /api/portal API — log in with POST /api/portal/login to get a token, then manage bots, knowledge, bring-your-own keys and analytics. It never returns stored API keys.