Quickstart

What you need

• A Ma Belle Note account on the Pro plan, or on the free trial: the API is included in both.
• The owner or admin role on the account: only they can create keys.
• A terminal with curl, or any tool that can send an HTTPS request.

Read operations, for locations, statistics, reviews, private feedback and contacts, are stable, like GET /v1/health, GET /v1/openapi.json and GET /v1/me: they follow the guarantees of the versioning guide. The event log, webhooks, writes and publishing to Google are in beta: they may still change before they are declared stable.

1. Create a key

In the app, open Settings › Integration, API & webhooks, then Create a key. Give it a name that says where it will be used, such as “Group dashboard”, pick the Read only template, then confirm.

The key starts with mbn_live_. It is shown only once: copy it and store it in a secrets manager. If you lose it, revoke it and create a new one.

2. Check that the API responds

GET /v1/health needs no key. It answers as long as the API is up, with the server time.

curl https://api.mabellenote.com/v1/health

{
  "object": "health",
  "status": "ok",
  "apiVersion": "v1",
  "time": "2026-10-24T09:15:02.311Z"
}

3. Make your first call

Put the key in an environment variable, then call GET /v1/me. Any valid key can call it: the response describes the account, the key and its rate limit.

export MBN_API_KEY="mbn_live_..."

curl https://api.mabellenote.com/v1/me \
  -H "Authorization: Bearer $MBN_API_KEY"

{
  "object": "me",
  "account": {
    "id": "kd7a1b2c3d4e5f6g7h8j9k0m1n2p3q4r",
    "name": "Le Bistrot",
    "slug": "le-bistrot",
    "plan": "pro",
    "readOnly": false
  },
  "apiKey": {
    "id": "jx9k2m4n6p8q0r1s3t5v7w9y1z3b5c7d",
    "name": "Group dashboard",
    "prefix": "mbn_live_AbC1",
    "scopes": [
      "account:read",
      "establishments:read",
      "reviews:read",
      "stats:read",
      "feedbacks:read"
    ],
    "createdAt": "2026-10-24T09:15:02.311Z",
    "expiresAt": null
  },
  "rateLimit": { "limit": 120, "windowSeconds": 60 }
}

A 401 response means the key is missing, unknown, revoked or expired: the code field tells you which. The errors guide covers them all.

4. List your locations

curl https://api.mabellenote.com/v1/establishments \
  -H "Authorization: Bearer $MBN_API_KEY"

Each location carries an id, its Google connection status (connection) and its review counters (reviews). Keep a location's id: it filters the other lists.

5. Read your reviews

curl "https://api.mabellenote.com/v1/reviews?establishmentId=kh2n8p5r3t6v9b1c4d7f0g2j5k8m1n3p&limit=10" \
  -H "Authorization: Bearer $MBN_API_KEY"

The list starts with the most recent review. Each review carries its rating, its text, its published reply (reply, or null) and its analysis (analysis). When hasMore is true, the next page comes with nextCursor.

The same call in JavaScript, in a Node 18+ module:

const response = await fetch("https://api.mabellenote.com/v1/reviews?limit=10", {
  headers: { Authorization: `Bearer ${process.env.MBN_API_KEY}` },
});
const body = await response.json();
if (!response.ok) throw new Error(`${body.status} ${body.code} (${body.requestId})`);
for (const review of body.data) console.log(review.rating, review.comment);

Next steps

• Authentication and scopes: a key's lifecycle, scopes and plan.
• Pagination and sync: walk through a list and fetch only what is new.
• Webhooks: receive every new review on your server and verify its signature.
• Writes: feed the customer base, record visits, redeem promo codes.
• No-code recipes: plug the API into Make, Zapier or n8n.
• AI assistant: ask Claude about your reviews, through the API's MCP server.
• Errors: the error format and the full list of codes.
• Limits: the allowed rate and the headers that announce it.
• API reference: every operation, every field.