MAVOS
Developers

An API that treats your
data like it’s yours.

A REST API for orders, products, bookings, availability, discounts and locations — plus signed webhooks for everything that moves, and an MCP server for AI assistants. Customers, memberships and the module apps are next. Ship stock tooling, booking widgets, IoT, or anything else that needs to live alongside your tills.

Getting startedDownload OpenAPI 3.1 specAI assistants (MCP)Contact

Scoped API keys

Company-wide keys with only the permissions an integration needs, optional location limits and an expiry. Issue and revoke them from the admin.

Signed webhooks

84 event kinds with wildcard subscriptions. HMAC-SHA256 signatures with replay protection, and up to 12 attempts with exponential backoff.

Idempotency-Key

Required on writes. The same key and body returns the stored response for 24 hours, so a network retry never doubles an order.

MCP for AI apps

Connect Claude, ChatGPT, Cursor and others by signing in or with an API key. AI rules keep money, keys and contact details out of reach.

REST API

The basics.

Base URL
https://mavos.com.au/api/v1, described by the OpenAPI 3.1 spec at /api/v1/openapi.json.
Authentication
Authorization: Bearer mavos_live_…. Owners and admins create keys at Settings → Integrations → API, Webhooks & AI apps. Older pos_live_ keys keep working.
Permissions
Keys are company-wide and carry permissions such as products:read or orders:write, with optional location limits and an expiry. Customer names need customers:names; emails and phones need customers:contact. Without them those fields come back null.
Idempotency
Writes need an Idempotency-Key header (1–255 characters). The same key and body replays the stored response with Idempotent-Replayed: true; a different body answers 409 idempotency_conflict.
Pagination
?limit= (1–200, default 50) and ?cursor=. Lists answer { "data": [...], "next_cursor": "…", "has_more": true }.
Money and time
Money is integer cents. Timestamps are ISO 8601.
Errors
{ "error": { "code", "message", "request_id", "details" } } with stable codes such as insufficient_scope, validation_failed and rate_limited.
Headers
Every response carries Mavos-Request-Id, Mavos-Api-Version: 2026-10-06 and X-RateLimit-Limit / -Remaining / -Reset.
AI assistants (MCP)

Connect Claude, ChatGPT and other AI apps.

The Mavos MCP server lives at https://mavos.com.au/api/mcp. AI apps can look up sales, products, bookings and more, and make the changes you allow — never beyond the permissions granted or the connecting person’s role. Available on every plan.

Sign in (OAuth)

For Claude, ChatGPT, Cursor, VS Code and any client that supports custom connectors.

  1. Add https://mavos.com.au/api/mcp as a custom connector.
  2. The client discovers sign-in from /.well-known/oauth-protected-resource and opens Mavos.
  3. Sign in, tick the businesses the app may use and the permissions for each.

The connection acts as you and can never exceed your role in each business. A business that requires two-factor sign-in asks for it before connecting. With more than one business, every tool takes a company argument and get_context lists the choices; over REST, send Mavos-Company.

API key

For clients that can send headers, such as Claude Code. The key’s permissions apply, plus the AI rules below.

claude mcp add --transport http mavos https://mavos.com.au/api/mcp \
  --header "Authorization: Bearer mavos_live_…"

Any other client: send Authorization: Bearer mavos_live_… on every request. Streamable HTTP, stateless with JSON responses; protocol versions 2025-11-25, 2025-06-18 and 2025-03-26.

AI rules

Every MCP connection follows these, including an API key used through MCP. A refused call answers ai_forbidden. AI can never:

  • Create or change orders, take payments or issue refunds
  • Issue or adjust gift cards, or change loyalty balances
  • Sign customers up to memberships or cancel them
  • Manage webhooks, API keys or users
  • See customer email addresses or phone numbers

Customer names are shown only with the “See customer names” permission. Everything is audit-logged under the person who connected the app. People disconnect apps at My account → Connected AI apps; owners and admins see and disconnect every AI connection for the business at Settings → Integrations → API, Webhooks & AI apps.

Tools and resources

get_context
The business, its locations and modules, who the app acts for, its permissions and the AI rules.
search_operations
Find API operations by keyword, module or read/write.
describe_operation
The input schema, result shape and permissions for one operation.
call_read_operation
Run a read operation. Never changes anything.
call_write_operation
Run a write operation, with the AI rules applied.
query_data
Read-only SQL over the business's data with personal details masked. Only with the Query data permission.

Resources: mavos://events/catalogue (every event kind) and mavos://query/tables (the tables query_data can read).