API Reference

This is the exhaustive contract surface for memo. Every route below is implemented in apps/memo/src/pages/api/.

Owner API — /api/owner/*#

All owner endpoints are Clerk-gated. The handler calls requireOwner(context) which resolves the Clerk session, looks up the matching memo.users row via clerk_user_id, and returns 401 if either fails. Subsequent ownership checks (e.g., projects.owner_id) are explicit per-route.

Projects#

All file routes path-validate via normalizeProjectPath (segments match [A-Za-z0-9._-]+, no .. / . / empty).

Links#

LinkCreateInput schema (zod, in src/lib/validation/link.ts):

{
  projectId: uuid;
  versionId: uuid;
  slug: string;             // /^[a-z0-9][a-z0-9-_]{1,63}$/
  name: string;             // 1..120
  requireEmail?: boolean;
  verifyEmail?: boolean;    // requires OTP
  password?: string;        // 4..200, will be argon2id hashed
  allowEmails?: string[];   // lowercase emails
  blockEmails?: string[];
  allowDomains?: string[];
  blockDomains?: string[];
  requireAgreementId?: uuid;
  allowDownloads?: boolean;
  expiresAt?: ISO8601;
  watermark?: boolean;      // default true
  welcomeMessage?: string;
  welcomeDisplayName?: string;
  customButtonLabel?: string;
  customButtonUrl?: url;
  branding?: object;
}

Agreements#

Access tokens (PAT)#

OAuth connections (owner-facing revoke)#

AI#

Projects v3 — rename, notes, versions, rollback, export#

Projects v3.x — editor IDE + observability#

These are the endpoints the IDE shell, Changes panel, find-in-files, section analytics, people timeline, and live activity feed consume.

GET /api/owner/projects/<id>/changes

Git-status-style diff: staged files vs the project's current published version. Modified detection compares stored sha256 (from memo.files) against on-the-fly sha256 of staged bytes. Capped at 1000 files per side (413 with detail if exceeded).

// 200
{
  "fromVersion": { "id": "<uuid>", "versionNumber": 3 },
  "added":     ["src/new-file.ts"],
  "removed":   ["docs/old.md"],
  "modified":  ["index.html"],
  "unchanged": 12
}
// when no version is current yet:
{
  "fromVersion": null,
  "added":     ["index.html", "style.css", ...],
  "removed":   [],
  "modified":  [],
  "unchanged": 0
}

GET /api/owner/projects/<id>/versions/<versionId>/files/<...path>

Streams a single file from a published version. Used by the editor's Monaco DiffEditor as the "original" (left) side of a diff. Ownership verified by a join across files → versions → projects → owner. Cache: private, max-age=300.

200 OK
content-type: <mime from memo.files>
<file bytes>

POST /api/owner/projects/<id>/search

Find-in-files. Owner-gated, rate-limited 30/min per (user, project).

// request
{
  "query": "TODO",
  "regex": false,
  "caseSensitive": false
}

// 200
{
  "matches": [
    { "path": "src/app.ts", "line": 42, "col": 8, "snippet": "// TODO: handle errors" }
  ],
  "truncated": false,
  "fileCount": 1,
  "matchCount": 1
}

// 400 on bad regex
{ "error": "invalid_regex" }

Per-file cap: 50 matches. Global cap: 500 matches (truncated: true when hit). Skips binary image files (isBinaryImageMime). Audit-logged with action project.search.

GET /api/owner/projects/<id>/analytics/sections

Per-section dwell aggregation from the Mongo time-series (type: "section_exit" events). Sorted by avg dwell descending. Cache: private, max-age=30.

// 200
{
  "sections": [
    {
      "id": "hero",
      "totalViews":      42,
      "uniqueVisitors":  18,
      "totalMs":         123456,
      "avgMs":           2939,
      "p50Ms":           2500,
      "p90Ms":           9800,
      "firstViewMs":     3200
    }
  ],
  "totalVisits": 47,
  "ms":          18
}

firstViewMs is the average dwell on the first time a visitor saw the section (per visit_id), useful for separating "first impression" attention from "they came back to re-read".

GET /api/owner/projects/<id>/activity/since?ts=<iso>

Polled by the Activity tab every 8 seconds. Returns visits with started_at > ts, oldest-first. Capped at 50 per poll. Joins visit_signals so badge chips arrive with the visit.

// 200
{
  "visits": [
    {
      "id":             "<uuid>",
      "startedAt":      "ISO-8601",
      "endedAt":        "ISO-8601 | null",
      "visitorEmail":   "string | null",
      "emailHash":      "<16-char base64url> | null",
      "linkId":         "<uuid>",
      "linkName":       "string",
      "linkSlug":       "string",
      "country":        "string | null",
      "city":           "string | null",
      "durationMs":     "number | null",
      "completionPct":  "number | null",
      "engagementScore":"number | null",
      "signals":        ["skim" | "deep_read" | "return" | "share_detected"]
    }
  ],
  "serverTime": "ISO-8601"
}

When ts is missing/invalid, defaults to now - 60s. The server-computed emailHash saves the client from re-implementing sha-256 just to link to /u/<username>/people/<emailHash>.

Webhooks (v3)#

Recording v3#

versionHash = sha256(contentHtml) is computed server-side and frozen into every subsequent signature.

Spaces (data rooms)#

All behind withOwner; every [id] route re-confirms spaces.owner_id = caller. See Spaces.

Teams & Diligence#

Q&A (owner) + NDA templates#

Cloud-storage OAuth connect#

<provider> ∈ {google, dropbox, box} (allowlisted). See Integrations.

Collaboration & realtime#

All behind withOwner and gated by requireProjectAccess(projectId, userId) (owner or project_members row). Members API mutates project_members / project_invites; the realtime routes mint scoped transport tokens for live co-editing. See Collaboration.

Visitor API — /api/v/<slug>/*#

All visitor endpoints are JWT-gated. The handler calls loadLink(slug) first; if the link isn't ok (not_found / inactive / expired), the response is 404 / 403 / 410 respectively.

Each returns 303 See Other to nextStep(link, claims). Ratelimits documented in Security.

Space gates — /api/s/<spaceSlug>/*#

Same four gate steps as links, built from the shared factories but validated against the space JWT.

In-viewer Q&A — /api/<slug>/qa#

Recording (rrweb) — scope-aware#

POST /api/recording/rrweb/events now accepts scope: "link" | "space". The space path validates the space gate and stores visit_recordings.space_id (with link_id = NULL); the R2 blob stays keyed by project_id+visit_id. See Replay.

Telemetry#

POST /api/beacon#

Body (sent via navigator.sendBeacon):

{
  slug: string;
  visit: string;                    // visitor JWT sub
  scope?: "link" | "space";         // default "link"; "space" for data-room views
  events: Array<{                   // .max(50) — at most 50 events per batch
    type: "page_view" | "page_leave" | "scroll_depth" | "click_zone"
        | "focus_change" | "gate_passed" | "download"
        | "section_enter" | "section_exit" | "media_progress";
    payload?: object;     // type-specific
    t?: number;           // unix ms; defaults to server time
  }>;
}

The handler:

1. Ratelimits 60/min/(slug, IP).
2. Verifies that the visit JWT cookie matches body.visit.
3. Asserts the visitor has actually passed all gates (nextStep(link, claims) === "view").
4. Inserts events into the Mongo time-series collection in one batch.

Always returns 204 No Content. Failures are silently dropped (telemetry must not retry-storm).

POST /api/recording/logrocket#

Body:

{ visit: string; url: string }     // url must start with https://app.logrocket.com/

Round-trips LogRocket's getSessionURL() callback onto visits.logrocket_session_url. See Recording.

MCP API — /api/mcp#

POST errors:

• 401 missing_bearer_token — no Authorization header. Response includes WWW-Authenticate: Bearer realm="memo", resource_metadata="…/.well-known/oauth-protected-resource" so clients can pivot into the OAuth flow.
• 401 invalid_token — bearer didn't resolve (PAT revoked / OAuth token expired / unknown).
• 429 rate_limited — sliding-window cap hit.

See /memo/mcp for the JSON-RPC method table and tool surface.

OAuth API — /oauth/*#

Cron API — /api/cron/*#

All cron endpoints accept either:

• GET with Authorization: Bearer ${CRON_SECRET} (Vercel native), or
• POST with Upstash-Signature header (QStash).

Owner pages (read-only HTML)#

These aren't "API" but documenting the contract:

Visitor pages#

Annotations (D4)#

Inline deck annotations — click-to-place pins on the project preview with threaded comments. Any project member may create and view; delete is restricted to the annotation author or a project manager.

Create body schema (Zod):

z.object({
  xPct: z.number().int().min(0).max(100),
  yPct: z.number().int().min(0).max(100),
  body: z.string().min(1).max(4000),
})

xPct / yPct are integer percentages (0–100) relative to the top-left corner of the preview iframe. The client computes them from getBoundingClientRect() at click time. Stored as integers to avoid float precision drift.

Annotation object:

{
  id: string,
  projectId: string,
  authorUserId: string,
  authorEmail: string,
  xPct: number,
  yPct: number,
  body: string,
  resolvedAt: string | null,
  createdAt: string,
}

All mutations are audit-logged via the audit() helper.

Notification preferences (C1.1)#

Auth: Clerk. PATCH is additive — omitted fields are left unchanged. Setting slackWebhookUrl to null clears it.

Cohort retention (C3)#

Auth: Clerk + project ownership. See Observability → Cohort retention grid for the full response schema.

Error shape#

All API endpoints return JSON for non-2xx responses where reasonable:

{ error: "invalid_input" | "slug_taken" | "version_not_in_project" | ...,
  issues?: ZodIssue[] }

Some endpoints (e.g., the publish route on compile failure) return the full esbuild error array:

{ status: "error", errors: Message[], warnings: Message[], durationMs: number }