The muro REST API: a developer quickstart

muro has a small, versioned REST API. If you can make an HTTP request you can read your inbox, send replies, and sync contacts into whatever you are building. JSON in, JSON out, one key. This is the quickstart that gets you from zero to a working call.

Base URL and auth

Everything lives under https://muro.chat/api/v1. The version is in the path, so we never break you silently. Pass your key as a Bearer token on every request:

bashcurl https://muro.chat/api/v1/conversations \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx"

The response envelope

Lists always return the same shape: an object of list, a data array, a has_more flag, and a next_cursor. Single resources carry their own object discriminator (conversation, message, contact). That consistency means you can write one helper and reuse it everywhere.

json{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "conv_8f2a",
      "status": "open",
      "unread_count": 1,
      "visitor": { "id": "vis_19c", "name": "Marie", "email": "[email protected]" },
      "last_message": { "content": "Is the Pro plan...", "sender_type": "visitor", "at": "2026-06-05T09:12:04Z" },
      "updated_at": "2026-06-05T09:12:04Z"
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0wNi0wNVQwOToxMjowNFp8Y29udl84ZjJh"
}

Sending a reply

POST to a conversation's messages collection with the write scope. Set kind to agent for a visitor-visible reply, or note for an internal note your team sees but the visitor does not. You get the created message back with a 201.

bashcurl -X POST \
  https://muro.chat/api/v1/conversations/conv_8f2a/messages \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "content": "On it, give me 5 minutes.", "kind": "agent" }'

Pagination

Lists are keyset-paginated, so deep paging stays fast and is stable even while new conversations arrive. When has_more is true, pass next_cursor back as ?cursor= to get the following page. Use ?limit= (up to 100) to size each page.

bashcurl "https://muro.chat/api/v1/conversations?limit=50&cursor=MjAy..." \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx"

Errors and rate limits

Any non-2xx response returns { "error": { "type", "message" } } with a matching HTTP status. The types you will see:

• →authentication_error (401) — missing or invalid key
• →permission_error (403) — the key lacks the scope this call needs
• →invalid_request_error (400) — a parameter is wrong or missing
• →not_found (404) — no such resource in your workspace
• →rate_limit_error (429) — you are going too fast

You get 120 requests per minute per key. Every response carries X-RateLimit-Remaining; a 429 also includes Retry-After in seconds. Back off and retry and you are fine.

A tiny Node client

No SDK needed. A thin wrapper around fetch is enough to cover the whole API:

typescriptconst BASE = 'https://muro.chat/api/v1';
const KEY = process.env.MURO_KEY as string;

async function muro(path: string, init: RequestInit = {}) {
  const res = await fetch(BASE + path, {
    ...init,
    headers: {
      Authorization: 'Bearer ' + KEY,
      'Content-Type': 'application/json',
      ...(init.headers ?? {}),
    },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? res.statusText);
  return body;
}

// List open conversations
const { data } = await muro('/conversations?status=open');

// Reply to the first one
await muro('/conversations/' + data[0].id + '/messages', {
  method: 'POST',
  body: JSON.stringify({ content: 'Thanks for reaching out!' }),
});

That is the whole surface. The full reference, with every endpoint and field, lives at /docs/api. Grab a key, paste the first curl, and you are building in a minute.