Modality REST API

Authentication

There are two distinct auth boundaries. Choose the one that matches your caller, they are not interchangeable.

1. Session cookies, the REST surface (/api/v1/*)

Modality uses Auth.js (NextAuth v5) with a JWT session strategy. When you sign in, the browser (or the mobile app) receives a session cookie that is sent automatically with every request. Server code resolves it with getAuthContext(), which returns the caller's workspaceId, userId, and workspace role. There is currently no Bearer-token authentication on the /api/v1 surface, sending an Authorization header there does nothing, and an unauthenticated request returns 401 { "error": "Not authenticated" }.

2. API keys, the MCP surface (/api/mcp)

For machine callers (agents, scripts, integrations) Modality issues workspace API keys in the format mk_live_<random>. A key authenticates only the MCP server at POST /api/mcp, where getMcpAuthContext() resolves the key to its owning workspace. The key is hashed (SHA-256) at rest; the plaintext is shown to you exactly once at creation.

curl -X POST https://modalitystudio.com/api/mcp \
  -H "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Authorization & Permissions

Being authenticated is not enough, every mutating route also checks a role permission via requirePermission(role, '<resource>:<action>'). Permissions follow a resource:action shape, e.g. contacts:read, contacts:write, events:read, events:write, invoices:write, integrations:write, analytics:read. Some routes (e.g. creating a custom object type) require Owner/Admin via requireAdmin(role).

• 401 { "error": "Not authenticated" }, no valid session.
• 403 { "error": "Forbidden: requires contacts:write permission" }, session is valid but the role lacks the permission.
• 403 with a plan-limit payload, the workspace hit a plan cap (see Errors). Enforced by enforcePlanLimit().

Response Format

// Single item
{ "data": { "id": "...", ... } }

// List (with a total count)
{ "data": [ ... ], "total": 42 }

// Create, returns 201 with the created resource
{ "data": { "id": "...", ... } }

Errors

Errors use standard HTTP status codes and one of the following JSON bodies:

// 400, Zod validation failure (details is the list of issues)
{ "error": "Invalid input", "details": [ { "path": ["email"], "message": "Required" } ] }

// 401, not signed in
{ "error": "Not authenticated" }

// 403, role lacks the permission
{ "error": "Forbidden: requires events:write permission" }

// 403, plan cap reached (shape varies by limit)
{ "error": "You've reached your plan's contact limit", "limit": 500, "current": 500, "upgradeUrl": "..." }

// 404, not found / not owned by this workspace
{ "error": "Event not found" }

// 409, conflict (e.g. deleting a ticket type that has sold tickets)
{ "error": "This ticket type has sold tickets, so it can't be deleted..." }

// 429, rate limited
{ "error": "Too many requests" }

// 500, unexpected server error
{ "error": "Failed to fetch contacts" }

Contacts (People)

Manage CRM contacts with tags, lists, custom statuses, custom fields, and activity timelines. Contacts are the same records surfaced as "People" in the app. Permissions: contacts:read / contacts:write.

{
  "data": [
    {
      "id": "clx...",
      "email": "user@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "phone": null,
      "source": "form",
      "status": "ACTIVE",
      "tags": [{ "id": "...", "name": "VIP", "slug": "vip" }],
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 1842
}

{ "data": { "id": "clx...", "email": "user@example.com", ... } }

{
  "results": [ { "email": "a@x.com", "status": "created" }, ... ],
  "summary": { "created": 150, "updated": 23, "errors": 2 }
}

Related CRM helpers:

Lists, Segments, Tags & Fields

Segmentation lives in Modality (ESPs are only delivery destinations). Tags are simple labels; lists are static memberships; segments are saved rule sets that resolve to a live audience.

Events

Create and manage events, ticket types, RSVPs, orders, promo codes, and door operations. Permissions: events:read / events:write.

{
  "data": [
    {
      "id": "clx...",
      "title": "Summer Festival",
      "slug": "summer-festival",
      "status": "PUBLISHED",
      "visibility": "PUBLIC",
      "startsAt": "2026-07-15T18:00:00Z",
      "endsAt": "2026-07-15T23:00:00Z",
      "venue": "Outdoor Arena",
      "ticketTypes": [
        { "id": "...", "name": "GA", "price": 4500, "capacity": 2000 }
      ]
    }
  ],
  "total": 5  // count of items returned, not a paginated total
}

{ "data": { "id": "clx...", "slug": "summer-festival", ... } }

Ticket types

Checkout

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/...",   // hosted redirect
    "clientSecret": "cs_...",                             // when using Embedded Checkout
    "orderId": "clx..."
  }
}

RSVPs, orders & door operations

A large surface of event sub-resources ships today. The canonical "attending" predicate for an RSVP is approved: true and declinedAt: null.

Point of sale (door)

Tickets & Orders

Read issued tickets and orders, look up a ticket for check-in, and generate wallet passes.

Forms & Submissions

Build dynamic forms (multi-page, conditional logic, theming, payment) and collect submissions. Submitting a form upserts a Person and stores the submission.

{
  "data": {
    "id": "clx...",
    "formId": "clx...",
    "contactId": "clx...",
    "paymentUrl": "https://..."   // priced forms only
  }
}

Form sub-resources:

Campaigns

Create and send email campaigns. Delivery goes through an ESP connector, or (where enabled) native sending. Permissions: campaigns:read / campaigns:write.

Campaign tooling:

Sequences

Multi-step drip sequences with enrollments. Permissions reuse the automations set: automations:read / automations:write. A cron worker advances enrollments.

Automations

Trigger → action workflow rules. Permissions: automations:read / automations:write.

Custom Objects

Define custom data structures (Deals, Sponsors, …) with typed attributes and records. Permissions: objects:read for reads; creating an object type requires Owner/Admin.

{
  "data": [
    {
      "id": "clx...",
      "name": "Deals",
      "slug": "deals",
      "singularName": "Deal",
      "icon": "Briefcase",
      "attributes": [
        { "name": "Stage", "type": "select", "options": [...] },
        { "name": "Value", "type": "currency" }
      ]
    }
  ]
}

Object sub-resources:

Invoices

Native invoicing with numbering, sending, payments, and stats. Permissions: invoices:read / invoices:write. Lists return { data, total }.

Integrations (ESP connectors)

Connect ESPs (Brevo, Mailchimp, Klaviyo) as delivery destinations. Connectors share a common interface and support OAuth. Permissions: integrations:read / integrations:write.

Analytics

Workspace stats, activity feed, and aggregates. Permission: analytics:read. Responses are { data }.

Domains

Custom sending domains for branded email. Gated behind the custom_domains feature (Business plan).

API Keys Management

Issue and revoke the mk_live_ keys used by the MCP server. Business-gated (api_access) and requires workspace:manage. These endpoints are called by the Settings → API UI; the plaintext secret is returned once on create.

{ "data": [ { "id": "...", "name": "Zapier", "scopes": ["crm:read"], "lastUsedAt": "...", "expiresAt": null } ] }

{ "data": { "id": "...", "name": "Zapier", "scopes": ["crm:read"], "secret": "mk_live_..." } }

MCP / AI Access

POST /api/mcp is a Model Context Protocol server (JSON-RPC 2.0, Streamable-HTTP), the purpose of the mk_live_ keys. It lets AI agents and scripts operate on your workspace through a curated set of tools, with the workspace bound to the key (never to request input) and every call scope-checked.

Scopes a key can carry (grant the least you need):

Webhooks

Modality delivers outbound webhooks to your endpoints when things happen in your workspace, and it also receives inbound webhooks from Stripe, Resend, and Twilio.

Outbound: subscribe to workspace events

Register endpoints and Modality will POST a signed JSON payload to them. This is a shipped feature, manage endpoints via the API or in Settings.

{ "data": [ { "id": "...", "url": "https://...", "events": ["order.completed"], "status": "ACTIVE" } ] }

Subscribable event types:

POST https://your-endpoint.example.com
X-Webhook-Event: order.completed
X-Webhook-Timestamp: 2026-09-02T10:30:00.000Z
X-Webhook-Signature: <hex hmac-sha256>

{
  "event": "order.completed",
  "timestamp": "2026-09-02T10:30:00.000Z",
  "workspaceId": "clx...",
  "data": { "orderId": "clx...", "eventId": "clx...", "total": 9000, ... }
}

Inbound: Stripe

Point your Stripe webhook (platform and Connect) at /api/v1/webhooks/stripe. The following events are handled:

• checkout.session.completed, fulfills ticket orders, issues tickets, sends confirmation.
• checkout.session.expired, releases held inventory for an abandoned checkout.
• customer.subscription.updated, applies plan changes.
• customer.subscription.deleted, handles cancellation/downgrade.
• invoice.paid, records a successful subscription payment.
• invoice.payment_failed, flags a billing problem.

Inbound: Resend, Twilio & email

Rate Limits

Rate limiting uses sliding-window presets keyed per workspace (ws:<id>), or per client IP on public endpoints like checkout. There are no per-plan tiers. The presets:

A limited request returns 429 with body { "error": "Too many requests" } and these headers:

• Retry-After, seconds until you can retry.
• X-RateLimit-Limit, the window's ceiling.
• X-RateLimit-Remaining, 0 on a limited response.
• X-RateLimit-Reset, epoch ms when the window resets.