Skip to content

API conventions

Everything below applies uniformly across the REST API.

Base URL and content type

https://{your-workspace}.muntri.com/api
Content-Type: application/json

Authentication recap

Two credential types (details in Authentication):

  • JWT bearer tokens for user sessions: Authorization: Bearer <jwt>
  • API keys for machine access: Authorization: ApiKey mnt_live_... or Authorization: Bearer mnt_live_... (both accepted). API keys are governed by scopes.

Pagination

List endpoints accept limit and offset query parameters and return either a plain array or an envelope:

{ "items": [...], "total": 412, "limit": 25, "offset": 0 }

Default page size is 25–50 depending on the endpoint; the maximum is stated per endpoint (commonly 200). Iterate by advancing offset until fewer than limit items return.

List endpoints take resource-specific query filters (for example status, owner_id, account_id) plus a free-text search parameter where supported. The reference lists each endpoint's query parameters; the machine-readable detail is in GET /api/openapi.json.

Errors

Errors use conventional HTTP status codes with a JSON body:

{ "detail": "Human-readable explanation" }
Status Meaning
400 Malformed request or invalid value
401 Missing/invalid credentials, expired key or token
403 Authenticated but not allowed: missing scope, RBAC permission, or IP not in allowlist
404 Record not found (or not visible in your workspace)
409 Business-rule conflict — e.g. booking a deal that fails the booking gate; the body lists the blockers
422 Validation failure; the body details the offending fields
429 Rate limit exceeded — back off and retry
5xx Server error; safe to retry idempotent requests

Rate limits

Sensitive endpoints carry per-IP rate limits (login 5/min, public capture endpoints 5–10/min). Connected Apps set per-app ceilings (default 60/minute, 10,000/day) that apply to all keys issued under the app. Handle 429 with exponential backoff.

Writes, idempotency and audit

  • POST creates, PATCH partially updates, PUT replaces where offered, DELETE deletes. Deletes require the delete scope action on API keys.
  • Every write is attributed: change history records whether a human, an AI agent, or an API key (Connected App) made the change, and webhook events fire through the transactional outbox.
  • Timestamps are ISO-8601 UTC; ids are UUIDs.

Versioning and stability

The API is unversioned-stable: fields are added, not repurposed, and breaking changes are announced in workspace release notes ahead of time. The OpenAPI spec your workspace serves always describes exactly what that workspace runs.