Mojeeb Public API
The Mojeeb Public API lets your backend, automation platform or AI client act on your
Mojeeb workspace with an API key: see which key you hold and which agents it can act on;
read and change an agent's settings (its name, Main Instructions, time zone, AI handoff
and comment auto-hide); send WhatsApp messages and templates, list a WhatsApp number's templates and read
their delivery status; read and edit contacts, their notes and leads; assign, filter, pin
and delete leads, and change the agent's lead fields and the prompt that decides when its
AI saves a lead; manage an agent's knowledge; switch the AI on or off per channel for
messages and comments; read the agent's conversations and their messages, change their
state and assignee, and reply as your team; read the agent's Facebook and Instagram
comments and hide or show them; get the agent's website widget and its embed code; set when the AI
follows up with quiet customers; give an agent custom API tools that call your own
system; read an agent's daily analytics; list your team,
including who can be assigned an agent's leads; and read your plan and this period's
usage. Start with GET /v1/me (the key itself) and GET /v1/agents (its agents). An
agent's endpoints live at /v1/agents/{agentId} (its settings) and under it (contacts,
notes, leads, lead fields, lead capture, knowledge, connections and their WhatsApp
templates, conversations and their messages, comments, website widget, follow-ups, custom
API tools, members, analytics), with an
id from that list;
the WhatsApp send endpoints take agent_id in the body. Company-wide reads (your team,
your plan and usage) live under /v1/organization/. Every failure uses one error
envelope, with one exception: a request body not sent as JSON
(Content-Type: application/json) gets a 415 in ASP.NET's standard problem-details
shape.
Lists. Contacts, notes and leads are cursor-paginated (limit, cursor; the
response carries next_cursor and has_more), and so are conversations, their messages,
comments and a custom API tool's runs.
Smaller lists (agents, members, lead fields, knowledge bases, connections, WhatsApp
templates, custom API tools, usage periods) come whole as
{ "items": [...] }. Analytics come as one report: a row per UTC day and the window's
totals.
Partial updates. PATCH changes only the fields you send; a field sent as null counts
as not sent, and fields an endpoint doesn't take are ignored, except that updateAgent
refuses the agent fields a key can't change (422 field_not_writable). custom_fields
merges key by key, and a key sent as null stays with the value null. Its values are
stored as sent, with two exceptions. A string in ISO 8601 date-time form with seconds (e.g.
2026-10-11T10:00:00+03:00) is stored and returned in UTC with Z and at most 6
fractional digits (2026-10-11T07:00:00Z); one with no offset is read as UTC and gains
Z. Non-integer numbers keep double precision (19.990 comes back as 19.99). Dates
without a time, and times without seconds, are kept as sent. To keep a local wall-clock
time, send it without an offset.
Body size. Request bodies may be up to 1 MB.
Who did it. A key acts for its company with the access of an agent admin on its agents. Where Mojeeb records a person (a note's author, a lead's status change or assignment), it records the person who created the key.
Rate limits. Each key has a per-minute request budget across the API (429 says how
it works). An endpoint with an x-rate-limit-per-minute of its own (today
listWhatsAppTemplates and sendConversationMessage) has a lower limit, counted
separately.
Stability promise. Everything under /v1/ is forever-stable: additive changes only
(new fields, new error codes, new endpoints). Any breaking change requires /v2/.
Scopes. Each operation names the scope it requires in x-scope; none means any valid
key may call it, whatever its scopes. Keys are issued with full access (*) today, so every
key passes; per-resource scopes can be issued later without changing this contract.
team:read, usage:read and analytics:read have no write scope: the API reads your
team, your plan and usage, and your analytics, and never changes them.
This document is the contract. The API serves it at
https://api.mojeeb.app/v1/openapi.yaml; the rendered reference lives at
https://docs.mojeeb.app/docs/developers/api-reference.
Authentication
- HTTP: Bearer Auth
Server-to-server API key issued from the Mojeeb dashboard. Treat like a database password — store in a secret manager, never embed in client-side code.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | mk_live_22-base62-chars_10-char-checksum |
Contact Mojeeb support: