POST /v1/replay

POST /v1/replay

GET /v1/response_stream is at-most-once with no resume — anything it delivered while nothing was listening is gone from the stream. /v1/replay is the backfill: ask for past command settlements and past inbound messages by the boundary you supply.

Like handle-check, this is a synchronous read. The answer is in the HTTP response; nothing arrives on the stream. The server keeps no per-client cursor — it is stateless, and you tell it where to resume.

Two independent lenses, either or both per call:

• commandIds — re-fetch how specific commands settled.
• conversationId (+ optional sinceExternalId) — re-fetch inbound messages in one conversation.

Request

# Re-settle specific commands you queued.
curl $MAPIER_BASE_URL/v1/replay \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commandIds": ["cmd-1", "cmd-2"]
  }'

Response

{
  "commands": [
    {
      "commandId": "cmd-1",
      "logicalActionId": "order-2481",
      "status": "succeeded",
      "errorCode": null
    }
  ],
  "messages": [
    {
      "conversationId": "a0000000-0000-4000-8000-000000000001",
      "from": "+14155550100",
      "text": "did it go through?",
      "externalId": "6F1B2C3D-0000-4000-8000-000000000002",
      "replyToExternalId": null,
      "occurredAt": "2026-08-24T18:03:11.000Z",
      "attachmentIds": []
    }
  ]
}

commands is present only if you sent commandIds; messages only if you sent conversationId. Each array holds the exact same object shape as the matching response_stream event:

• commands[] — one entry per command that was found, identical to a command event (commandId, logicalActionId, status, errorCode, plus conversationId on a successful group.create). The count can be smaller than the ids you asked for; missing ones were unknown or not yours.
• messages[] — inbound messages only, identical to a message event, oldest first.

How messages are ordered and anchored

• Order is arrival order — the sequence the server received the messages in, not occurredAt. occurredAt is what iMessage stamped and can be backdated, so it is not the cursor.
• sinceExternalId is exclusive — the anchor message itself is never returned, only messages after it. Pass the newest externalId you have and you get strictly what you are missing.
• No sinceExternalId returns the most recent limit messages, still oldest-first within the page.
• No dedup. Replay does not know what you have already applied. Re-apply by externalId — seeing a message you already have must be idempotent. This is the same discipline the stream asks for, so a client that keys on externalId needs no extra logic.

Errors

A call with neither commandIds nor conversationId is valid and returns {}.

Related