Using these docs with AI agents

If you are pointing a coding agent or an LLM at this API, you do not have to scrape the HTML. Every page here is also published as plain markdown at a stable URL.

Three machine-readable views

The per-page form mirrors the page URL. /docs/api/message-send is published at /llms.mdx/docs/api/message-send/content.md:

curl https://docs.mapier.ai/llms.mdx/docs/api/message-send/content.md

All three are plain text over HTTP. There is no authentication, no key and no rate limit to negotiate — they are the same public pages in a different representation.

Which one to reach for

/llms.txt for navigation. It is small, so it fits comfortably in a system prompt or a first tool call. An agent that reads the index can then fetch only the two or three pages a task actually needs, which keeps the context focused and the answers grounded in the right page.

/llms-full.txt for a complete dump. Use it when you want the whole API in one context window and can afford the tokens — a one-shot integration, a migration review, a question that could touch anything. It is the same content as the site, concatenated into a single document.

A single page for a targeted fetch. When you already know the subject — error codes, the stream contract, the group commands — fetch that page alone. It is by far the cheapest option and the least likely to bury the relevant paragraph.

A reasonable default is: load /llms.txt once, then fetch pages on demand.

Prompting against this API

Two facts about this API contradict what a model has learned from every other messaging API it has seen, and both produce code that looks correct and is quietly broken. State them explicitly in your prompt rather than hoping the docs get read closely enough.

A 202 is not a delivery confirmation. It means the command was queued. Agents routinely write a send() that returns as soon as the HTTP call succeeds, and then a caller that reports success. The real outcome arrives later as a command event on GET /v1/response_stream, and it can be failed — including for a malformed payload, which is not validated at the API boundary.

Idempotency-Key does not work on every command. It is honoured on conversation-target sends, tapbacks, reaction.apply and name_photo.share, and accepted-then-ignored on recipient-target sends, group.create, group.update and group.leave. An agent writing a generic retry wrapper will assume the header is universal and produce a client that duplicates messages under load — or reuse a key after its command has settled, which adopts the old command and sends nothing at all.

Something like this, pasted alongside your task, is usually enough:

The Mapier iMessage API returns 202 when a command is QUEUED, not delivered.
Never report success from the HTTP response. Subscribe to GET /v1/response_stream
and wait for the `command` event carrying that commandId; only a `succeeded`
status means the send was accepted by iMessage.

Idempotency-Key is honoured only on message.send with a conversation target,
reaction.tapback, reaction.apply and name_photo.share. On message.send with a
recipient target, group.create, group.update and group.leave it is silently
ignored, so a retry duplicates the effect. Do not write one retry wrapper that
assumes all commands are idempotent. A key is bound to its command forever:
reuse it for an in-flight retry, but use a NEW key for a deliberate resend
after the command has settled, or the call is adopted and nothing is sent.

It is also worth telling an agent that there are no webhooks and no client SDK — the SSE stream is the only push channel, and every example in these docs is raw fetch or curl. Left to itself, a model will happily invent an npm install @mapier/imessage step.

Related