## API reference

Base URL `https://a1lane.ai`. Authenticate with `Authorization: Bearer <token>`: a session token (`ses_…`) or a workspace-scoped API token (`plt_…`) with scopes `read ⊂ write ⊂ publish`. Tenant routes live under `/api/v1/workspaces/{ws}`; a workspace you cannot see is a 404. Errors are JSON `{error, detail}`; plan limits answer 402 with `detail.code = plan_limit` and an upgrade URL. Rate limits: sign-up, login and reset throttles; per-token limits on the MCP surface; platform pacing per account with `deferred` states instead of failures.

194 routes, generated from the running application. Changes and the deprecation policy: [API changelog](/docs/changelog).

| Method | Path | Summary |
| `GET` | `/.well-known/oauth-authorization-server` | RFC 8414 discovery for the product's own OAuth 2.0 authorization server. |
| `GET` | `/.well-known/oauth-protected-resource` | RFC 9728: tells MCP clients which authorization server protects /mcp/v1. |
| `GET` | `/.well-known/oauth-protected-resource/mcp/v1` | RFC 9728: tells MCP clients which authorization server protects /mcp/v1. |
| `GET` | `/.well-known/openai-apps-challenge` | R-30: ChatGPT apps domain-verification challenge — the token comes from config only. |
| `GET` | `/api/v1/admin/analytics` | admin analytics |
| `GET` | `/api/v1/admin/billing` | admin billing |
| `GET` | `/api/v1/admin/engagement` | Leg 7: engagement pipeline counts across workspaces (counts only, no tenant data). |
| `GET` | `/api/v1/admin/mcp` | R-35: per-tool call volume, error rate and latency across the deployment (?token= for one token). |
| `GET` | `/api/v1/admin/mcp/funnel` | DESIGN-V2 §8: the assistant journey funnel, attributed by OAuth client. |
| `GET` | `/api/v1/admin/quota` | Leg 5b operator surface: every ledger bucket with its current-window usage. |
| `PUT` | `/api/v1/admin/quota/{key}` | PUT {capacity, source?}: a verified number (e.g. the Cloud Console allocation) drops in |
| `GET` | `/api/v1/admin/scheduler` | Leg 5d item 6: the tick gauge alone (fleet p95 + per-workspace, with its trip lines). |
| `GET` | `/api/v1/admin/stats` | admin stats |
| `GET` | `/api/v1/admin/throttles` | Leg 5b item 13 operator surface: durable throttle state (hits per kind / hashed key). |
| `POST` | `/api/v1/auth/login` | auth login |
| `POST` | `/api/v1/auth/logout` | auth logout |
| `POST` | `/api/v1/auth/reset/confirm` | auth reset confirm |
| `POST` | `/api/v1/auth/reset/request` | auth reset request |
| `POST` | `/api/v1/auth/signup` | auth signup |
| `POST` | `/api/v1/auth/verify-email` | auth verify email |
| `POST` | `/api/v1/billing/webhook` | Stripe → us. Public route; the signature is the only credential. Raw body, no parsing |
| `POST` | `/api/v1/data-deletion/callback` | Meta → us (Facebook Login / Instagram / Threads). Public; the signature is the only |
| `GET` | `/api/v1/engagement/coverage` | Leg 7: the public per-platform × metric coverage/freshness matrix, generated from code. |
| `GET` | `/api/v1/health` | health |
| `GET` | `/api/v1/invites/{token}` | invite preview |
| `POST` | `/api/v1/invites/{token}/accept` | invite accept |
| `DELETE` | `/api/v1/me` | me delete |
| `GET` | `/api/v1/me` | me |
| `GET` | `/api/v1/me/2fa` | me 2fa |
| `POST` | `/api/v1/me/2fa/disable` | me 2fa disable |
| `POST` | `/api/v1/me/2fa/enroll` | me 2fa enroll |
| `POST` | `/api/v1/me/2fa/recovery-codes` | me 2fa recovery |
| `POST` | `/api/v1/me/2fa/verify` | me 2fa verify |
| `GET` | `/api/v1/me/export` | me export |
| `PUT` | `/api/v1/me/password` | me password |
| `GET` | `/api/v1/me/preferences` | Amendment 8a: the user's own display defaults (timezone, locale). |
| `PUT` | `/api/v1/me/preferences` | Amendment 8a: the user's own display defaults (timezone, locale). |
| `GET` | `/api/v1/me/sessions` | me sessions |
| `POST` | `/api/v1/me/sessions/revoke-all` | me sessions revoke all |
| `DELETE` | `/api/v1/me/sessions/{id}` | me session revoke |
| `POST` | `/api/v1/me/verify-email/resend` | me verify resend |
| `POST` | `/api/v1/meta/deauthorize` | Meta → us when a person removes the app: Facebook Login / Instagram "Deauthorize Callback |
| `GET` | `/api/v1/plans` | Public: the plan configuration the pricing page renders (one source of truth). |
| `GET` | `/api/v1/platforms` | platforms |
| `GET` | `/api/v1/receipts/{token}` | receipt link public |
| `GET` | `/api/v1/review/{token}` | review view |
| `POST` | `/api/v1/review/{token}/decision` | review decide |
| `GET` | `/api/v1/review/{token}/media` | review media |
| `GET` | `/api/v1/status` | Public status page data: service health + rolling delivery-verification rates, aggregated |
| `GET` | `/api/v1/upload-links/{token}` | upload link public status |
| `PUT` | `/api/v1/upload-links/{token}/chunks/{n}` | upload link chunk |
| `POST` | `/api/v1/upload-links/{token}/complete` | upload link complete |
| `POST` | `/api/v1/upload-links/{token}/session` | upload link session |
| `GET` | `/api/v1/workspaces` | list workspaces |
| `POST` | `/api/v1/workspaces` | create workspace |
| `DELETE` | `/api/v1/workspaces/{ws}` | delete workspace |
| `GET` | `/api/v1/workspaces/{ws}` | get workspace |
| `PUT` | `/api/v1/workspaces/{ws}` | rename workspace |
| `GET` | `/api/v1/workspaces/{ws}/accounts` | list accounts |
| `POST` | `/api/v1/workspaces/{ws}/accounts` | connect account |
| `DELETE` | `/api/v1/workspaces/{ws}/accounts/{id}` | disconnect account |
| `GET` | `/api/v1/workspaces/{ws}/accounts/{id}` | get account |
| `GET` | `/api/v1/workspaces/{ws}/accounts/{id}/best-times` | Leg 7: best-time-to-post suggestions from this channel's own history (or not enough data). |
| `GET` | `/api/v1/workspaces/{ws}/accounts/{id}/choices` | Leg 4: option values the platform enumerates for this account (e.g. Pinterest boards). |
| `POST` | `/api/v1/workspaces/{ws}/accounts/{id}/pause` | pause account |
| `POST` | `/api/v1/workspaces/{ws}/accounts/{id}/probe` | probe account |
| `GET` | `/api/v1/workspaces/{ws}/accounts/{id}/queue` | account queue |
| `POST` | `/api/v1/workspaces/{ws}/accounts/{id}/reconnect` | reconnect account |
| `POST` | `/api/v1/workspaces/{ws}/accounts/{id}/resume` | resume account |
| `PUT` | `/api/v1/workspaces/{ws}/accounts/{id}/settings` | account settings |
| `GET` | `/api/v1/workspaces/{ws}/analytics` | workspace analytics |
| `GET` | `/api/v1/workspaces/{ws}/attention` | attention |
| `GET` | `/api/v1/workspaces/{ws}/batches` | list batches |
| `GET` | `/api/v1/workspaces/{ws}/batches/{id}` | get batch |
| `GET` | `/api/v1/workspaces/{ws}/batches/{id}/receipt-links` | list receipt links |
| `POST` | `/api/v1/workspaces/{ws}/batches/{id}/receipt-links` | create receipt link |
| `GET` | `/api/v1/workspaces/{ws}/benchmarks` | Leg 7: tracked public profiles (official routes only) with their latest numbers. |
| `POST` | `/api/v1/workspaces/{ws}/benchmarks` | Leg 7: track a public profile; refused with the reason where no official route exists. |
| `DELETE` | `/api/v1/workspaces/{ws}/benchmarks/{id}` | Leg 7: stop tracking a profile (its stored numbers go with it). |
| `GET` | `/api/v1/workspaces/{ws}/billing` | workspace billing |
| `POST` | `/api/v1/workspaces/{ws}/billing/checkout` | billing checkout |
| `POST` | `/api/v1/workspaces/{ws}/billing/portal` | billing portal |
| `POST` | `/api/v1/workspaces/{ws}/billing/reconcile` | billing reconcile |
| `GET` | `/api/v1/workspaces/{ws}/calendar` | calendar |
| `GET` | `/api/v1/workspaces/{ws}/connections` | Item 8: connection health (``?account=`` narrows to one account). |
| `GET` | `/api/v1/workspaces/{ws}/connections/reconnect` | connections batch |
| `GET` | `/api/v1/workspaces/{ws}/digest` | Leg 6 item 3: the digest computed live for [since, until) (default: the last 24 hours) — |
| `GET` | `/api/v1/workspaces/{ws}/digests` | digest runs |
| `POST` | `/api/v1/workspaces/{ws}/digests/run` | Run the last complete period of a cadence now (owner/admin): idempotent per period. |
| `GET` | `/api/v1/workspaces/{ws}/duplicates` | Leg 5b item 8: the Phase-gate duplicate count (open and resolved). |
| `GET` | `/api/v1/workspaces/{ws}/engagement` | Leg 7: engagement rollups per channel / platform over the window (unavailable excluded, counted). |
| `GET` | `/api/v1/workspaces/{ws}/events` | events |
| `GET` | `/api/v1/workspaces/{ws}/export` | export |
| `GET` | `/api/v1/workspaces/{ws}/imports` | import list |
| `POST` | `/api/v1/workspaces/{ws}/imports/preview` | Leg 6 item 1: dry-run an export (hootsuite | generic | buffer_analytics); nothing is posted. |
| `GET` | `/api/v1/workspaces/{ws}/imports/{id}` | import view |
| `POST` | `/api/v1/workspaces/{ws}/imports/{id}/commit` | import commit |
| `GET` | `/api/v1/workspaces/{ws}/imports/{id}/rejected.csv` | import rejected csv |
| `GET` | `/api/v1/workspaces/{ws}/inbox` | The in-app notification feed (digests + R-41 alerts), minus the types the caller turned |
| `GET` | `/api/v1/workspaces/{ws}/ledger` | Ledger-first home: the newest receipts with their post + destination context. |
| `GET` | `/api/v1/workspaces/{ws}/mcp/idempotency/{tool}/{key}` | Leg 6 item 4(d): the durable idempotency record the stdio MCP server reads and writes |
| `PUT` | `/api/v1/workspaces/{ws}/mcp/idempotency/{tool}/{key}` | Leg 6 item 4(d): the durable idempotency record the stdio MCP server reads and writes |
| `GET` | `/api/v1/workspaces/{ws}/media` | Media library (leg 3, L2): filter by tag / kind / search; archived assets on request. |
| `POST` | `/api/v1/workspaces/{ws}/media` | add media |
| `DELETE` | `/api/v1/workspaces/{ws}/media/{id}` | delete media |
| `GET` | `/api/v1/workspaces/{ws}/media/{id}` | get media |
| `PUT` | `/api/v1/workspaces/{ws}/media/{id}` | update media |
| `GET` | `/api/v1/workspaces/{ws}/media/{id}/file` | media file |
| `GET` | `/api/v1/workspaces/{ws}/members` | list members |
| `POST` | `/api/v1/workspaces/{ws}/members` | invite member |
| `DELETE` | `/api/v1/workspaces/{ws}/members/{id}` | remove member |
| `PUT` | `/api/v1/workspaces/{ws}/members/{id}` | change member |
| `POST` | `/api/v1/workspaces/{ws}/members/{id}/resend` | resend invite |
| `POST` | `/api/v1/workspaces/{ws}/oauth/{platform}/choose` | oauth choose |
| `GET` | `/api/v1/workspaces/{ws}/oauth/{platform}/start` | oauth start |
| `GET` | `/api/v1/workspaces/{ws}/pause` | Leg 5b item 15: the workspace's durable pause state (workspace-wide + per-account). |
| `POST` | `/api/v1/workspaces/{ws}/pause` | pause workspace |
| `GET` | `/api/v1/workspaces/{ws}/posts` | list posts |
| `POST` | `/api/v1/workspaces/{ws}/posts` | create post |
| `POST` | `/api/v1/workspaces/{ws}/posts/batch` | create batch |
| `POST` | `/api/v1/workspaces/{ws}/posts/import` | Bulk CSV import (leg 3, L2): multipart 'file', text/csv body, or JSON {csv, mapping}. |
| `POST` | `/api/v1/workspaces/{ws}/posts/price-check` | Item 9(a): the composer's live X pricing — the same pass create_post's warnings use. |
| `DELETE` | `/api/v1/workspaces/{ws}/posts/{id}` | delete post |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}` | get post |
| `PUT` | `/api/v1/workspaces/{ws}/posts/{id}` | update post |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/approval` | post approval |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/cancel` | cancel post |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/acknowledge-divergence` | acknowledge divergence |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/confirm-deleted` | Q-DT-10 (G-30): confirm a manual delete no probe can settle (READBACK = False) — |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/continue-parts` | continue parts |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/decline-finish` | decline finish |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/finish` | finish view |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/finish-check` | Leg 6 item 2: run the destination's finish-check now and return the finish view. |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/mark-resolved` | Discord + Telegram leg (item 7, Q-DT-2): accept an unverifiable send as delivered — |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/missed-window` | Leg 5b item 6: decide a held missed window (publish_now | next_slot | reschedule | cancel). |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/observations` | Leg 5b item 4: the append-only observation records of one destination. |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/parts` | Leg 5b item 7: the destination's parts (thread parts, first comment, playlist add). |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/removal` | Leg 5b item 10: the ingestion seam for a platform removal event (no webhook receiver |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/reoffer` | reoffer finish |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/resolve` | resolve destination |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/resolve-duplicate` | Leg 5b item 8: keep one native copy (the others route through unpublish) or keep both. |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/support-bundles` | Leg 5b item 17: a destination's redacted support bundles (newest last). |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/destinations/{dest}/unpublish` | Leg 5b item 9: start the unpublish chain for one live destination. |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/duplicate` | duplicate post |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/engagement` | Leg 7: one post's engagement per destination — latest values with asOf, reasons, series. |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/handoff` | handoff |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/publish` | publish post |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/receipt-links` | list receipt links |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/receipt-links` | create receipt link |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/recycle` | create recycle |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/release` | release post |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/reschedule` | reschedule post |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/retry` | retry post |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/review-links` | list review links |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/review-links` | create review link |
| `DELETE` | `/api/v1/workspaces/{ws}/posts/{id}/review-links/{nonce}` | revoke review link |
| `GET` | `/api/v1/workspaces/{ws}/posts/{id}/revisions` | Item 7a: the append-only revision history of a post. |
| `POST` | `/api/v1/workspaces/{ws}/posts/{id}/revisions/{n}/restore` | Item 7a: restore revision N as a NEW revision (body may carry ``revision`` = the |
| `GET` | `/api/v1/workspaces/{ws}/quota/fit` | Leg 5b (C10): does a publish to ``account_id`` fit at ``at`` (default now), and if not, |
| `POST` | `/api/v1/workspaces/{ws}/receipt-links/{lid}/revoke` | revoke receipt link |
| `GET` | `/api/v1/workspaces/{ws}/recycles` | list recycles |
| `DELETE` | `/api/v1/workspaces/{ws}/recycles/{id}` | stop recycle |
| `GET` | `/api/v1/workspaces/{ws}/reports` | Leg 7: a composed report (delivery + engagement per channel, chosen window) as JSON or CSV. |
| `GET` | `/api/v1/workspaces/{ws}/reports/exports/{id}` | Leg 7: download one produced export (sign-in / token required; never mailed as an attachment). |
| `GET` | `/api/v1/workspaces/{ws}/reports/schedules` | Leg 7: scheduled exports (weekly/monthly) and the exports they produced, with their state. |
| `POST` | `/api/v1/workspaces/{ws}/reports/schedules` | Leg 7: schedule a weekly/monthly export mailed as a download link to workspace members. |
| `DELETE` | `/api/v1/workspaces/{ws}/reports/schedules/{id}` | Leg 7: stop a scheduled export (exports already produced stay downloadable). |
| `POST` | `/api/v1/workspaces/{ws}/resume` | resume workspace |
| `PUT` | `/api/v1/workspaces/{ws}/settings` | workspace settings |
| `PUT` | `/api/v1/workspaces/{ws}/settings/digest` | digest settings |
| `GET` | `/api/v1/workspaces/{ws}/settings/notification-preferences` | Amendment 3a: the caller's own per-type channel preferences (email / in_app), plus the |
| `PUT` | `/api/v1/workspaces/{ws}/settings/notification-preferences` | Amendment 3a: the caller's own per-type channel preferences (email / in_app), plus the |
| `PUT` | `/api/v1/workspaces/{ws}/settings/notifications` | PUT {emails, webhook_url, webhook_secret?, events}: R-41 targets; the secret goes to the vault. |
| `PUT` | `/api/v1/workspaces/{ws}/settings/onboarding` | PUT {step: done|skipped|pending}: resumable, skippable onboarding steps (L5). |
| `PUT` | `/api/v1/workspaces/{ws}/settings/shortener` | PUT {provider, domain?, token?}: the token goes to the vault, never to settings/export. |
| `PUT` | `/api/v1/workspaces/{ws}/settings/x-caps` | Item 9(c): owner/admin edit the workspace's soft/hard X caps (the 5b breaker enforces). |
| `GET` | `/api/v1/workspaces/{ws}/tokens` | list tokens |
| `POST` | `/api/v1/workspaces/{ws}/tokens` | create token |
| `DELETE` | `/api/v1/workspaces/{ws}/tokens/{id}` | revoke token |
| `GET` | `/api/v1/workspaces/{ws}/tokens/{id}/usage` | Leg 6 amendment 4a: one token's MCP usage — the operator endpoint's own numbers. |
| `POST` | `/api/v1/workspaces/{ws}/upload-links` | create upload link |
| `GET` | `/api/v1/workspaces/{ws}/upload-links/{id}` | upload link status |
| `POST` | `/api/v1/workspaces/{ws}/uploads` | create upload |
| `GET` | `/api/v1/workspaces/{ws}/uploads/{id}` | upload status |
| `PUT` | `/api/v1/workspaces/{ws}/uploads/{id}/chunks/{n}` | upload chunk |
| `POST` | `/api/v1/workspaces/{ws}/uploads/{id}/complete` | complete upload |
| `GET` | `/api/v1/workspaces/{ws}/usage/x` | Item 9(b): the month's X spend — confirmed vs estimated, never blended — with pace and caps. |
| `GET` | `/mcp/listing.json` | R-30: directory listing metadata (name, description, icon, categories) from one place. |
| `GET` | `/oauth/{platform}/callback` | Platform redirect target (no login needed: the one-time state binds workspace + user). |
| `GET` | `/oauth2/authorize` | Consent page: login (or sign-up) → choose workspace + scopes → Allow. |
| `POST` | `/oauth2/authorize` | authorize submit |
| `POST` | `/oauth2/register` | Register a public OAuth client (assistants register themselves on first connect). |
| `POST` | `/oauth2/revoke` | RFC 7009: revoke an access or refresh token. Always 200 (no token enumeration). |
| `POST` | `/oauth2/token` | Authorization-code (PKCE) and refresh-token grants; refresh rotates both tokens. |

---
HTML version: https://a1lane.ai/docs/api