Wanderlust API documentation

Quickstart

1. Sign up at /developers/signup. Your first team + key get created together.
2. Copy the key (shown exactly once). Manage future keys at /dashboard/api-keys.
3. Send it in the Authorization header. That's it.

curl https://wanderlustapp.io/api/public/v1/me \
  -H "Authorization: Bearer wl_live_xxxxxxxx_..."

Authentication

The API accepts your key in either of two headers — pick whichever your HTTP client makes easier.

Authorization: Bearer wl_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyy

X-Api-Key: wl_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyy

Keys are secrets: never commit them to source control or ship them in client-side bundles. Treat them like database passwords. You can revoke a key instantly from the dashboard if it leaks.

Teams & members

Personal keys are great for prototypes. Real teams should use organizations — a shared workspace with role-based access, invite-by-email, team-owned keys, and a shared usage dashboard.

Create one from /dashboard/organizations. You become the owner; invite anyone by email and they'll join after accepting at /accept-invite/{token}.

Team-owned keys inherit the team's plan, so an admin can upgrade once and every key gets the higher limits. The full account API for managing orgs (/api/account/organizations/*) is cookie-authenticated and intended to power custom dashboards — see the team dashboard for the reference UI.

Webhooks

Subscribe to platform events — new members, key changes, subscription updates — and we'll POST them to a URL of your choosing. Configure them from your team dashboard → Webhooks.

Events

invite.created, invite.accepted, invite.revoked, member.added, member.removed, member.role_changed, key.created, key.revoked, key.deleted, key.quota.warning, key.quota.exceeded, subscription.updated.

Headers we send

Content-Type: application/json
User-Agent: wanderlust-webhooks/1.0
X-Wanderlust-Event: key.created
X-Wanderlust-Event-Id: evt_abc123…
X-Wanderlust-Signature: t=1716392400,v1=<hex>
X-Wanderlust-Timestamp: 1716392400

Verifying the signature

Compute HMAC-SHA256(timestamp + "." + raw_body, signing_secret) and compare it to the v1= value. Reject anything whose timestamp is more than five minutes old to defeat replays.

import crypto from "node:crypto";

function verify(req, secret) {
  const sig = req.headers["x-wanderlust-signature"] || "";
  const tsHeader = req.headers["x-wanderlust-timestamp"];
  const ts = Number(tsHeader);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${req.rawBody}`)
    .digest("hex");
  const provided = sig.split(",").find((p) => p.startsWith("v1="))?.slice(3);
  return !!provided && crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(provided, "hex")
  );
}

Example payload

{
  "id": "evt_abc123",
  "type": "key.created",
  "created_at": "2026-05-22T18:00:00.000Z",
  "organization_id": "65fab…",
  "data": {
    "key_id": "65fab…",
    "prefix": "wl_live_a1b2c3d4",
    "name": "Production backend",
    "plan": "pro",
    "created_by": "65f01…"
  }
}

Respond with any 2xx status within 8 seconds. Non-2xx responses count as failures — the dashboard surfaces the last status and consecutive failure count.

Billing

Upgrades, downgrades, and card management run through Stripe. Owners hit Upgrade to Pro in team settings, complete Checkout, and every team-owned key inherits the new limits immediately. Payment failures keep the API live for a short dunning window (past_due status); a hardcanceled drops the team back to Free.

Manage your card, invoices, and cancellation from the Stripe Customer Portal — accessible from the same Settings page.

Rate limits

Limits are per API key, enforced per minute. Every response includes the current limit headers — inspect them before backing off.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 47
X-Wanderlust-Plan: pro

When you exceed the per-minute budget the API returns 429 Too Many Requests with a Retry-After header. Wait that many seconds before retrying.

Pagination

List endpoints accept page (default 1) and limit (default 25, max 100). Responses include total, page, and has_more so you can paginate without guessing.

{
  "object": "list",
  "page": 2,
  "limit": 25,
  "total": 196,
  "has_more": true,
  "count": 25,
  "data": [ /* ... */ ]
}

Errors

All errors share a consistent shape so clients can dispatch on a single code path.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (120 requests/min on the pro plan).",
    "docs": "https://wanderlustapp.io/developers/docs#errors"
  }
}

Endpoints

Everything you can call today, in one place.