Skip to content
MSO CloudDocumentation

API reference

On this page

The internal application API behind the MSO Cloud web app: tRPC v11 (superjson and Zod) at /api/trpc/[trpc], plus a few plain HTTP routes. It is not a versioned public contract; each procedure's description is the comment above it in the source.

Router groups#

Group Routers Scope
Sign-in and workspace health, me, orgs, users, brands, passkeys, socialIdentities, orgAuthLdap, orgAuthOidc, orgLoginPage Session context, members, organizations and brands, passkeys and organization sign-in.
Dashboards and exploration dashboards, dashboardGridDraft, dashboardTemplates, dashboardSubscriptions, dashboardVersions, insights, explore, brandCompare, orgDatasetInsights Dashboards, templates, versions and delivery, Explore, brand comparison and AI insight cards.
Commerce data orders, creators, inventory, products, subscription, attribution, audiences, cases, activation, campaigns, reports, marketplace Orders, products, inventory, creators, reports and customer operations over the organization's own data.
Marketing performance marketing, leadsDiagnostic, marketingWeb, marketingLeads, marketingSocial, marketingCampaigns, planBindings Ad spend, web analytics, owned channels, leads and plan bindings from the organization's own sources.
Content Intelligence audienceLocalFilter, audienceTabScope, contentInsights, contentTaxonomy, contentDecks, audienceCards, audienceBriefMatch A conversation corpus: taxonomy, insights and presentation decks.
Data sources and datasets connectors, orgCredentials, connectorBackfill, pipeline, manualUploads, validation, categories, shopAliases, importTemplates, orgDatasets Connections, shared credentials, uploads, mapping templates, backfill, validation and organization datasets.
Market and social intelligence marketIntel, socialListening, socialTrends The third-party estimate plane, kept apart from first-party validation and from chat.
Signals and decisions alerts, alertWorkflows, briefing, actions, memos, playbooks, offtake, msoPlaybooks, signals Signals, alerts, the morning brief, actions, playbooks, memos and the decision ledger.
AI and chat aiConfigs, platformAiConfigs, aiPrompts, chat, chatAssistant The data assistant, per-organization AI configuration and the prompt registry.
Notifications notifications, notificationSettings, notificationChannels The in-app inbox, channel configuration and per-organization notification policy.
Administration apiTokens, admin, siteIdentity, appearance, platformConnectors, orgData, orgBackupConfig, orgMenu, orgBlueprints, masking Platform administration, organization data and backup, menus, blueprints, appearance and masking.
Sharing and public shares, publicShare Dashboard and report share links, and public surfaces that need no sign-in.

REST routes#

Flows that need plain HTTP sit outside tRPC: sign-in, WebAuthn, streaming chat, webhooks, OAuth callbacks and exports. Mutating routes are rate-limited, and organization-scoped routes set the row-level security context before touching data. Only routes an integrator calls are listed; internal operating routes are not.

Route Methods
/api/apps/launch/[app] GET
/api/auth/[...nextauth] GET, POST
/api/auth/idp-handoff GET
/api/auth/magic-link POST
/api/auth/oidc/callback/[providerId] GET
/api/auth/oidc/start GET
/api/auth/passkey/auth/begin POST
/api/auth/passkey/register/begin POST
/api/auth/passkey/register/finish POST
/api/auth/reconcile GET
/api/auth/social/google/callback GET
/api/auth/social/google/confirm GET
/api/auth/social/google/start GET
/api/auth/sso GET
/api/auth/switch-brand POST
/api/auth/switch-org POST
/api/chat/deck POST
/api/chat POST
/api/compliance/dsar GET, POST
/api/connectors/oauth/[platform]/callback GET
/api/csp-report POST
/api/exports/dashboard-payload POST
/api/exports/page-pdf POST
/api/health GET
/api/ingest/webhook/[connectorType]/[connectorId] POST
/api/market-intel/category-export GET
/api/marketing-systems/summary POST
/api/metrics GET
/api/org-data/[id]/download GET
/api/platform/v1/events POST
/api/platform/v1/me/launcher GET
/api/platform/v1/me GET
/api/platform/v1/orgs/[orgId]/brands GET
/api/platform/v1/orgs/[orgId]/entitlements GET
/api/platform/v1/orgs/[orgId]/members GET
/api/platform/v1/orgs/[orgId]/social/trend-feed/history GET
/api/platform/v1/orgs/[orgId]/social/trend-feed/items GET
/api/platform/v1/orgs/[orgId]/social/trend-feed GET
/api/platform/v1/orgs/[orgId]/social/trend-feed/search GET
/api/platform/v1/orgs/[orgId]/social/trends/counts GET
/api/platform/v1/orgs/[orgId]/social/trends GET
/api/ready GET
/api/trpc/[trpc] GET, POST
/api/webhooks/telegram POST
/api/webhooks/zalo POST

Tenancy bases#

Six base procedures in apps/web/src/server/trpc.ts; choosing a base chooses the data-isolation tier.

Base Requires Row-level security context
publicProcedure nothing none; public surfaces only (health, share links, wordmark)
authedProcedure a signed-in user none; data the user owns (passkeys, my organizations)
superAdminProcedure isSuperAdmin cross-organization by design; every admin.* procedure
orgProcedure an activeOrgId in the session the whole resolver runs in one transaction carrying app.current_org_id (runWithRlsContext)
brandProcedure as orgProcedure adds app.current_brand_id; null means the whole-organization rollup
chatProcedure as brandProcedure adds the chat-with-data plugin gate and an owner or admin role

Access checks#

The Access column on each group page names the base plus any check the resolver runs, detected from the source:

  • owner or admin: requireOwnerOrOrgAdmin in apps/web/src/server/access.ts, a fixed role gate. It guards every learning-loop mutation, the playbook library, mapping administration, chat configuration and market-intelligence ingest.
  • A capability id such as manage_connectors: requireOrgCapability, the per-organization role policy. Ids match the Roles and capabilities matrix.

Organization-scoped mutations also pass rateLimitOrgMutation, and administrative actions write the audit log. Plugin entitlements are enforced at the page and the menu, not in tRPC; chatProcedure is the one exception.

Data conventions#

  • Money is integer VND, never numeric or float; displayed through @yng/charts/formatVnd.
  • Time is Asia/Ho_Chi_Minh (ICT) on every date path: day buckets are ICT-anchored in SQL, day edges and labels come from @yng/ui/ict-date, and charts receive the ISO string verbatim.
  • is_sample on every data table keeps sample data apart from real data.
  • Serialization is superjson (Date, Map and BigInt cross the wire intact); input is validated with Zod, and a validation error returns a flattened zodError.
  • Personal data is stored verbatim and masked on display through @yng/ui/mask; a response never carries a credential or secret.