v1
API documentation
The Ma Belle Note REST API reads an account's locations, reviews, statistics, private feedback and customer base, writes contacts, visits and reply drafts to it, and sends every event to your tools by webhook. An API key is all you need.
API documentationOverview
Base URL
Every operation starts from this address, over HTTPS, with the account key in the Authorization header.
https://api.mabellenote.com/v1
Read operations are stable: they follow the compatibility policy described in the versioning guide. An operation marked “Beta”, such as writes, webhooks or the event log, may still change before it is declared stable.
Guides
- QuickstartCreate a key, check the connection and read your first reviews in a few minutes.
- Authentication and scopesHow an API key is sent, what it covers, the scopes it carries and what the account's plan changes.
- Pagination and syncWalk through a list page by page with a cursor, then fetch only what is new on each run.
- WebhooksReceive every new review, private feedback or customer on your server, verify the Standard Webhooks signature, and handle retries, auto-disabling and replays.
- IdempotencySend a write again after a network failure without risking a duplicate, with the Idempotency-Key header.
- WritesFeed the customer base from a till or a CRM, record visits, redeem promo codes and drop reply drafts.
- Google publishingPublish from your tool the reply to a Google review, for the locations that allowed it, with the same checks as in the app.
- ErrorsThe API error format, how to handle errors and the full list of codes, each with its own anchor.
- LimitsThe rate allowed per key, the headers that announce it, what to do when you exceed it and the API's other limits.
- VersioningWhat may change within version v1, what never changes there, the beta status and how a version is deprecated.
- API referenceEvery operation, parameter, field and error, generated from the API itself.Open the reference
- ChangelogEvery change to the API contract, dated, newest first.
No-code recipes
Step-by-step guides to plug the API into Make, Zapier or n8n with their generic HTTP and webhook modules, or into an AI assistant, without writing a server.
- Google Sheets with MakeEvery night, one row per location in a Google Sheets spreadsheet: review count, average rating, replies and rating breakdown. A Make scenario, no code.
- Slack with ZapierA message in your team's channel as soon as a review of 2 stars or fewer comes in, with a webhook, Webhooks by Zapier and Slack, no code.
- Tickets with n8nAn n8n workflow that reads the event log every 5 minutes and opens a ticket for every review or private feedback of 2 stars or fewer.
- AI assistant (MCP)Plug Claude, ChatGPT, Le Chat or Claude Code into your reviews, statistics and private feedback via the API's MCP server: one address to paste, no key to copy.
Available operations
List taken from the OpenAPI description of the current version.
| Operation | Purpose | Required scope | Stability |
|---|---|---|---|
GET /v1/health | Check API availability | No key | Stable |
GET /v1/openapi.json | Get the OpenAPI description | No key | Stable |
GET /v1/me | Identify the API key | account:read | Stable |
GET /v1/establishments | List establishments | establishments:read | Stable |
GET /v1/establishments/{establishmentId} | Get an establishment | establishments:read | Stable |
GET /v1/establishments/{establishmentId}/stats | Get establishment statistics | stats:read | Stable |
GET /v1/reviews | List reviews | reviews:read | Stable |
GET /v1/reviews/{reviewId} | Get a review | reviews:read | Stable |
GET /v1/feedbacks | List private feedback | feedbacks:read | Stable |
GET /v1/feedbacks/{feedbackId} | Get private feedback | feedbacks:read | Stable |
GET /v1/contacts | List contacts | contacts:read | Stable |
POST /v1/contacts | Create or update a contact | contacts:write | Beta |
GET /v1/contacts/{contactId} | Get a contact | contacts:read | Stable |
PATCH /v1/contacts/{contactId} | Update a contact | contacts:write | Beta |
POST /v1/visits | Record a visit | visits:write | Beta |
POST /v1/promo-codes/redeem | Redeem a promo code | promo_codes:redeem | Beta |
POST /v1/reviews/{reviewId}/reply-drafts | Generate an AI draft | ai:generate | Beta |
PUT /v1/reviews/{reviewId}/reply-draft | Write a draft | replies:write | Beta |
POST /v1/reviews/{reviewId}/reply | Publish a reply to Google | replies:publish | Beta |
GET /v1/events | List events | events:read | Beta |
GET /v1/events/{eventId} | Get an event | events:read | Beta |
GET /v1/webhook-endpoints | List webhook endpoints | webhooks:manage | Beta |
POST /v1/webhook-endpoints | Create a webhook endpoint | webhooks:manage | Beta |
DELETE /v1/webhook-endpoints/{endpointId} | Delete a webhook endpoint | webhooks:manage | Beta |
POST /v1/webhook-endpoints/{endpointId}/test | Send a test event | webhooks:manage | Beta |