API reference

Getting started

Create a key in the app under Developer API. Keys look like mls_live_a1b2c3_… and are shown once — we store a hash, so we can't recover one for you.

curl https://api.maelstrom.it.com/v1/me \
  -H "Authorization: Bearer mls_live_a1b2c3_…"

Use mls_test_… keys while building. Every response carries X-Maelstrom-Units-Used and X-Maelstrom-Units-Remaining, so your integration can see its own consumption without a separate call.

Scopes

Keys carry only what you grant. Three presets cover most cases: Read only (8), Automation (12), Full access (16).

Errors

Errors are JSON with a stable code, a human message, and enough context to act on. 403 insufficient_scope names the scope you're missing; 402 quota_exhausted tells you when the allowance resets and confirms nothing was billed.

Discovery

Intents

Matching

Counterparts

Scheduling

Calendar [LIVE]

Three ways to give Maelstrom availability, and none is required: connect Google, subscribe to any published ICS URL, or state busy times directly. Everything below acts on your own calendar only — there is no scope that reads anyone else's.

Outlook and Microsoft 365 users: there is no OAuth connection, and there will not be — Graph offers no free/busy-only permission. Use POST /v1/calendar/feeds with the URL from Outlook's own Publish a calendar dialog, choosing Availability only. You grant us nothing, and you can verify that in your own settings. The trade: a published feed is not live and can lag a few hours. Connect Google if you need to-the-minute accuracy.

Programmes [LIVE]

For organisers: an accelerator, a fund's portfolio, an adviser's clients, a community, an event. These act on programmes you run (or your firm runs, if you are one of its admins), with what your programme workspace already shows. They are what a Zapier or Make step calls: invite everyone who fills in a form, or who joins your Circle community.

Rooms

OAuth — apps acting for other people [NOT BUILT — design only]

None of this section is callable today. See the status note at the top of this page. Use an API key instead; it covers your own data.

An API key is you acting on your own data. If you're building something other Maelstrom users install, each of them must consent individually and be able to withdraw that consent without affecting anyone else. That's OAuth, and it's what a marketplace app needs.

Register

Create an app in the dashboard under Developer API. You get a client_id and a client_secret (shown once). Apps start in development — usable by you alone — and go public after review, so a directory can't fill with impersonations.

1. Send the user to authorize

GET /oauth/authorize
  ?client_id=mapp_…
  &redirect_uri=https://yourapp.com/callback
  &scope=counterparts:read%20matches:read
  &state=<random, checked on return>
  &code_challenge=<BASE64URL(SHA256(verifier))>
  &code_challenge_method=S256

PKCE is mandatory, including for confidential clients. It costs you nothing and removes an entire class of interception attack. code_challenge_method must be S256.

Redirect URIs are matched exactly — no prefixes, no wildcards. Open redirects are how authorization codes get stolen.

2. Exchange the code

POST /v1/oauth/token
{
  "grant_type": "authorization_code",
  "code": "…",
  "client_id": "mapp_…",
  "client_secret": "msec_…",
  "redirect_uri": "https://yourapp.com/callback",
  "code_verifier": "…"
}

Returns an access token (mat_…, one hour) and a refresh token (mrt_…, 90 days). Use the access token exactly like an API key.

Codes are single-use. Presenting one twice means it leaked, so we revoke every token on that grant rather than guessing which use was legitimate. Handle code_already_used by starting the flow again.

3. Refresh

POST /v1/oauth/token
{ "grant_type": "refresh_token", "refresh_token": "mrt_…",
  "client_id": "mapp_…", "client_secret": "msec_…" }

Refresh tokens rotate. Each refresh invalidates the previous pair — store the new one or your next call fails.

Asking for more permissions later

Send the user through the same flow with the additional scope and merge: true. The consent screen then leads with what is new rather than re-listing everything they already approved — people stop reading a list they've seen before, which is exactly when a widened permission slips through unnoticed.

The authorize description returns incremental, new_scopes, existing_scopes, and dropped_scopes, so you can render this properly. Without merge, a new request replaces the grant — which is how an app narrows its own access.

Lifecycle events

Subscribe your app's webhook to these and stop discovering revocations through a 401:

These are app-only: a personal webhook cannot subscribe to them.

Sandbox [NOT BUILT]

There is no sandbox environment yet. Keys issued today are live keys against live data.

Build against a synthetic population instead of your own live account. Create one in the dashboard and you get ten people arranged in complementary pairs — a founder and an investor, a brand and a manufacturer, a seller and an acquirer — with real matches, conversations, and booked meetings between them.

curl https://api.maelstrom.it.com/v1/counterparts   -H "Authorization: Bearer mls_test_…"   -H "X-Maelstrom-Sandbox-User: 9003"

A test key acts as one of your sandbox people; omit the header and you act as the first. A test key can never reach a live account, and a live key never reaches the sandbox — the two are quarantined in both directions. Sandbox personas are excluded from real matching and never receive email.

The data is deliberately imperfect: one thread is left unanswered and not every match has a meeting, because a sandbox where everything is tidy teaches your app nothing about the cases it will actually meet.

One-click install links

Generate a signed link to put behind an "Add to Maelstrom" button on your own site. The signature covers the client id, the scopes, and the redirect — so nobody can edit the link to request more than your app advertises. A link that fails verification shows the user a warning instead of a consent screen.

Replaying events

Fire any subscribed event at your own endpoint on demand instead of waiting for a real user to do something — which is the actual blocker, since several events only occur when someone acts.

Replayed deliveries carry "replay": true in the payload. That's deliberate and loud: an app that treats a replay as real and emails a customer is a bug you want failing in testing, not quietly in production. Replays always fire on behalf of a sandbox user — never a real one, because a synthetic event carrying a real person's id would put fabricated data into your record of them.

Before you submit

Your dashboard runs the same checklist a reviewer does — description, website, tagline, privacy policy, HTTPS-only redirects, and whether the number of permissions you request is defensible. Nothing on it is secret, so you may as well clear it before submitting rather than after. Submission is refused while a required item is unmet, and the refusal shows you the list.

Changing your permissions later

Narrowing what you request applies immediately — nobody needs protecting from an app asking for less. Widening beyond what review approved sends the app back to review and pulls it from the directory until it's approved again, because an app with more power than users saw at install is materially a different app.

Existing installs are never retroactively widened. A grant holds exactly what that user approved; changing your app's requested scopes cannot reach into it. Send those users through authorization again with merge: true.

Delivery log

Every webhook delivery, with attempt count, the response we got back, latency, and whether it was a replay. Redelivering resets the existing entry rather than duplicating it, so the log stays readable.

Alerts

We email you when your app's error rate is high in absolute terms, or is far worse than other apps on the platform, or your webhook endpoint starts failing, or you're being throttled repeatedly. One alert per issue per week at most. A broken integration loses installs quietly, so waiting for you to open a dashboard is the wrong default.

Analytics

Your dashboard shows installs and uninstalls over time, calls and units by endpoint, errors broken out by status with what each one means, and a comparison against other apps on the platform — a 12% error rate means something different depending on whether the median is 4% or 11%. Where too few apps are comparable we say so rather than publishing a median nobody should act on. — a 403 (a scope you never requested) and a 429 (you're being throttled) call for completely different fixes. You also get specific suggestions rather than raw numbers to interpret.

What you can't do

• Request scopes beyond the ones your app registered — extras are dropped and reported, never silently granted.
• Escalate a user's own permissions. A token can never do more than the person could.
• Survive revocation. Users see every connected app with its permissions in plain language, and revoking kills your tokens for that person instantly — while leaving every other user's intact.

Webhooks

Rather than polling, register an HTTPS endpoint and we'll push events to it. Each delivery carries x-maelstrom-timestamp (Unix seconds) and x-maelstrom-signature: the hex HMAC-SHA256 of ${timestamp}.${rawBody} with your endpoint's signing secret. Verify it with a constant-time comparison and reject anything stale.

Failed deliveries retry with backoff; an endpoint that fails 20 times in a row is disabled and you're told why.

Limits and pricing

Usage is metered in units, not calls, because a matching run costs far more to serve than reading a profile. Pretending otherwise would either overcharge cheap calls or subsidise expensive ones.