How to call the API
Audience: both — developers and self-host operators calling the API directly.
Every action in the Marula web app, desktop app, and mobile app goes through the same /api/v1/… REST API. You can call those exact same endpoints from your own scripts using curl or the typed TypeScript client (@marula-core/sdk).
Prerequisites
- A reachable
core-apiserver and either a user bearer token (see the API first-ticket tutorial) or a scoped machine token from Settings → API keys (see How to manage API keys).
1. Authenticate
For interactive user scripts, send email and password to POST /api/v1/auth/login to receive an access/refresh token pair. For background scripts and integrations, create a scoped key in Settings → API keys.
Send your token on every request in the Authorization header:
Authorization: Bearer <your-token>2. Read paged collections
Read endpoints use standard GET /api/v1/… routes and support pagination query parameters (?limit=&offset=).
3. Write data and handle the instant-first envelope
Every POST, PATCH, PUT, or DELETE mutation returns Marula's instant-first mutation envelope containing the updated record, its new version, a monotonic sequence number, and the updated timestamp.
If someone else updated the same record at the same moment, the API returns a 409 Conflict with code version_conflict so your client can reconcile cleanly without overwriting their edit (see Instant-first doctrine).
4. Handle structured error codes
When a request is rejected, Marula returns a structured error object with a machine-readable reason code and a clear human message—so your scripts never have to regex-match error text. Common examples include:
org_slug_taken(includes a verified-availablesuggestionfield)already_seededboard_move_status_conflict
5. Use the typed TypeScript SDK
@marula-core/sdk is generated directly from the committed OpenAPI specification (the same spec that generates the API reference):
import { createClient } from "@marula-core/sdk";
const client = createClient({ baseUrl: "https://your-host" });6. Build external connectors
External connectors are standard web services that call the /api/v1/… REST endpoints and receive HMAC-signed webhooks. Check plugins/connectors/ (such as the NinjaOne and Hudu reference connectors) and How to extend Marula with plugin surfaces for working examples.