The public REST API

Availability and getting a key

The public REST API is available on the Standard plan and higher. It lets you manage chatbots, send chat messages, add training sources and read conversations and leads from your own code.

API keys are issued on request today. Ask for one in the chat on matram.ai and the team will set it up for you.

Authentication

Every request must carry your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Treat the key like a password. Call the API from your server and keep the key out of client-side code.

Rate limit

Each key can make up to 120 requests per minute. Space out bulk work, such as adding many sources, so you stay under that ceiling.

Messages sent through the chat endpoint count against your monthly message quota, the same as messages from the widget or a connected channel. When the quota is reached, the bot stops answering on all surfaces, including the API, until you upgrade, add the extra-messages add-on, or the billing cycle resets. See plans and usage limits for details.

Endpoints

The API has five endpoints:

• GET /api/v1/chatbots - list the chatbots in your workspace. POST to the same path creates a chatbot.
• POST /api/v1/chatbots/{id}/chat - send a message to a chatbot and receive its answer. This endpoint streams.
• POST /api/v1/chatbots/{id}/sources - add a training source to a chatbot.
• GET /api/v1/conversations - list conversations.
• GET /api/v1/leads - list captured leads.

Because the chat endpoint streams, the answer arrives progressively rather than as one block, the same way replies appear in the widget. Read the response as a stream if you want to show words as they are generated.

When you do not need the API

If all you want is chat on a web page, the script embed does that with one tag and no key. The Installation tab also shows a simple curl example for the widget chat endpoint. See embed options to pick the right route.