Build on SimpleInvite.

Get a key

curl https://app.simpleinvite.app/api/v1/me \
  -H "Authorization: Bearer si_live_..."

Make a key

How it behaves

Everything is scoped to your key

There is no account or organisation parameter. A key belongs to one host, and every list is that host's rows. An id from anywhere else returns a 404, not a 403 — the two answers would tell you something exists.

Every failure has one shape

Every failure is `{ error: { code, message } }`. Branch on `code`, which is stable; `message` is a sentence for a person and may be reworded. A 422 adds `details`, one entry per field that did not pass.

Lists page by cursor

Pass `limit` (up to 200) and the `next_cursor` from the page before. An offset would re-send rows when something is inserted mid-scan and skip rows when something is deleted; a cursor anchored on the last row cannot.

Reads carry an ETag

Send it back as `If-None-Match` and an unchanged read answers 304 with no body. Worth doing on the two heavy reads — an event's invitations, and the guest book.

Rate limits are per key

120 reads and 30 writes a minute. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, so you can back off before you are refused; a 429 carries `Retry-After` in seconds. Writes are the tighter budget because each one can put a message in front of a person.

Sending is separate from changing

Creating an event sends nothing. Adding a guest sends nothing. `POST /events/{id}/send` is the call that puts invitations on a wire, and it is idempotent — a retry after a timeout reports the first call's result rather than inviting everyone twice.

The rules are not negotiable through the API

Nudges are capped, quiet hours are honoured, someone who opted out is never messaged, and an answer goes through the same state machine a guest's tap does. Nothing here can do something a host could not have done by hand.

Reference

Generated from the same schemas the routes validate with. The machine-readable document is at /api/openapi.json. openapi.json

Webhooks

curl -X POST https://app.simpleinvite.app/api/v1/webhooks \
  -H "Authorization: Bearer si_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.org/hooks/simpleinvite","events":["rsvp.changed"]}'

{
  "id": "evt_m1x8k2q4b7",
  "type": "rsvp.changed",
  "created_at": "2026-09-11T18:04:22.117Z",
  "data": {
    "event_id": "evt_gamenight",
    "invitation_id": "inv_kims",
    "status": "accepted",
    "maybe": false,
    "headcount": 4,
    "response_channel": "web",
    "responded_at": "2026-09-11T18:04:22.101Z"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

export function verify(secret: string, body: string, header: string): boolean {
  const parts = new Map(
    header.split(",").map((part) => {
      const [name, value] = part.split("=");
      return [name, value] as const;
    }),
  );

  const timestamp = Number(parts.get("t"));
  const presented = parts.get("v1") ?? "";
  if (!Number.isFinite(timestamp) || !presented) return false;

  // Reject a delivery older than the window, or one dated in the future.
  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  if (expected.length !== presented.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(presented));
}

Deliveries are not a queue. We try twice, a second apart, and record what happened — a receiver that is down for a minute misses that delivery. Answer 2xx as soon as you have the body; do your work after.

MCP

Claude Code

claude mcp add simpleinvite \
  --transport http \
  https://app.simpleinvite.app/api/mcp \
  --header "Authorization: Bearer si_live_..."

Claude Desktop

{
  "mcpServers": {
    "simpleinvite": {
      "type": "http",
      "url": "https://app.simpleinvite.app/api/mcp",
      "headers": {
        "Authorization": "Bearer si_live_..."
      }
    }
  }
}

Tools whose description begins SENDS REAL MESSAGES put texts or email in front of actual guests. Read a tool's description before you let an agent call it unattended.