Domain API routes
The Domain API routes expose WorldMonitor monitoring data and product actions through one edge API. They serve the dashboard, paid API clients, shared briefs, embedded panels, feeds, AI clients, desktop sign-in, and account features. Shared edge rules keep access, limits, cache, freshness, and error behavior aligned across these route families. For the wider platform boundary, see API platform and Backend gateway routing.
Route surface
The route surface groups related product questions behind stable edge entry points. Domain routes provide monitoring data. Other families turn that data into briefs, searches, feeds, embedded views, agent tools, authorization flows, and account actions.
| Route family | Main purpose | Representative paths |
|---|---|---|
| Domain services | Return monitoring, market, research, risk, supply-chain, trade, orbital, and scorecard data | /api/intelligence/v1/..., /api/market/v1/..., /api/orbital/v1/..., /api/scorecard/v1/..., /api/supply-chain/v1/..., /api/trade/v1/... |
| Briefs | Read briefs, create share links, render pages, and add story context | /api/latest-brief, /api/brief/..., /api/internal/brief-why-matters |
| Searches and feeds | Find symbols, search external records, and read news or social feeds | /api/symbol-search, /api/rss-proxy, /api/intelligence/v1/search-gdelt-documents |
| Embeds and agents | Authorize embedded panels, issue panel grants, serve map data, stream analyst chat, and proxy agent requests | /api/embed/entitlement, /api/embed/session, /api/embed/map-frame, /api/chat-analyst, /api/widget-agent, /api/ask, /api/a2a |
| MCP | Expose tools, resources, prompts, skills, UI shells, and OAuth discovery to AI clients | /api/mcp, /mcp, /.well-known/mcp, /oauth/..., /docs/mcp |
| Product capabilities | Describe plans, create checkout sessions, issue keys, publish events, manage notifications, support desktop access, referrals, and partner data flows | /api/product-catalog, /api/create-checkout, /api/user-api-keys, /api/notify, /api/notification-channels, /api/desktop-key/status, /api/v2/shipping/... |
Contract boundary
Versioned JSON data routes use generated service contracts as the normal product boundary. A reviewed exception list covers external protocol envelopes, HTML and image responses, upstream feed relays, operational probes, and internal helpers that are not stable domain APIs. MCP tool definitions, aliases, resources, and OAuth code remain protocol surfaces rather than generated domain APIs.
References: api/api-route-exceptions.json• L1-10 api/api-route-exceptions.json• L41-120
Domain services
Monitoring domain groups
Each domain service presents related read and write operations under a versioned path. The edge route connects the public path to a domain handler, so conflict, natural events, aviation, markets, intelligence, trade, supply chains, resilience, orbital imagery, scorecards, and other areas share the same gateway rules. Service contracts define the request and response shapes.
These services answer four broad questions:
- What is happening now?
- What does it mean for a place, company, or market?
- Where are pressure points in trade and supply?
- What evidence and forecasts support the view?
GET operations normally take filters from the query string. POST operations normally carry JSON. Responses can include freshness, coverage, availability, degradation, or upstream status. These fields let a client distinguish an empty result from a failed or partial source.
References: api/…/[rpc].ts• L1-9 api/…/[rpc].ts• L1-12 api/…/[rpc].ts• L1-15 api/…/[rpc].ts• L1-9 src/…/service_server.ts• L1124-1157 src/…/service_server.ts• L127-171
Company monitoring
Company monitoring is an account-scoped product for tracking companies and material event impacts. It covers company setup, imports, lists, event impacts, evidence, coverage, and access status. Its responses describe the state of a customer’s monitoring view rather than a global news feed.
The route is private and uses no-store behavior until account isolation is proven end to end. This prevents one customer’s monitored companies or impacts from entering a shared cache.
References: src/…/service_server.ts• L4-35 src/…/service_server.ts• L104-155 server/gateway.ts• L425-441
Request gateway
Gateway sequence
The domain gateway is the common edge boundary for generated routes. It checks the request before dispatch and applies response rules after the handler returns. This keeps route families consistent even when their data sources differ.
The normal request path is:
flowchart LR
A[Request] --> B[Origin and trusted client checks]
B --> C[Preflight or authentication]
C --> D[Entitlement and rate limits]
D --> E[Route and request validation]
E --> F[Domain handler]
F --> G[Error and response headers]
G --> H[Cache policy, ETag, and projection]
H --> I[Response]
The edge checks that client IP headers came through the trusted Cloudflare path before using them for tight IP budgets. A missing proof fails closed for sensitive IP-scoped routes. The gateway accepts a compatible POST for some older GET clients and converts simple JSON parameters into a query request. An unknown path returns 404. A known path with the wrong method returns 405 with an Allow header.
References: api/_cors.js• L145-216 api/_rate-limit.js• L187-269 server/gateway.ts• L881-923 server/router.ts• L29-106
Access classes
Access depends on both the route and the credential. An entitlement is the current account decision about a plan and its allowed features. Anonymous access can serve basic or explicitly public data. Paid domain paths use a validated bearer session or user API key. Enterprise keys represent operator-issued access. MCP calls can use OAuth bearer credentials or user API keys and resolve both to the same account budget.
| Access class | Typical use | Resulting rule |
|---|---|---|
| Public request | Selected shared dashboard reads and lead capture | No user credential, with an exact path and query shape |
| Anonymous session | Basic dashboard reads and first-party feeds | Basic access and rate limits, without paid entitlement |
| User API key | Programmatic paid API access and MCP access | Key owner, key kind, scopes, and active API entitlement apply |
| Clerk bearer | Signed-in Pro or paid product access | Session identity and current entitlement apply |
| Enterprise key | Operator or enterprise access | Enterprise policy and per-key limits apply |
| Desktop key | Self-hosted desktop or relay access | Desktop client checks, owner limits, and desktop entitlement apply |
| Free MCP path | Catalog reads and explicitly free MCP tools | Public metadata is limited by IP; free data calls use a tighter fail-closed IP limit |
| Internal MCP request | Pro MCP tool calling a domain route | Signed internal request is checked again |
Public access is decided from the URL before a cache can answer. A credentialed response cannot become public because a caller used an unexpected query or credential. MCP metadata remains discoverable without a paid entitlement, while credentials presented on public methods are still checked rather than silently downgraded to anonymous access. A small registry-defined MCP tool set can return data without a credential, but it uses a separate fail-closed limit.
References: api/_user-api-key.js• L245-360 api/_user-api-key.js• L479-569 api/…/status.ts• L163-212 api/…/auth.ts• L445-547 api/…/handler.ts• L1215-1349
Edge request safeguards
The shared edge helpers protect the route boundary before product work begins. CORS trusts listed WorldMonitor app hosts, controlled preview hosts, local desktop hosts, and selected translated first-party origins. It keeps credentialed responses private and exposes retry, rate, billing, migration, and bounding-box headers that clients need.
Rate limits use trusted IP or account identifiers. General traffic can remain available during a Redis fault, but session issuance, session-bound writes, free MCP data, analytics health writes, and other abuse-sensitive actions return a retryable degraded response. Account API access also has a per-minute burst limit and a daily usage meter. The daily meter can be shared by REST and MCP for API plans. Write routes can use an idempotency key so a retry returns the stored result instead of repeating the action.
References: api/_cors.js• L11-94 api/_rate-limit.js• L152-269 api/_api-key-rate-limit.js• L129-189 api/_idempotency.js• L149-299 api/…/auth.ts• L1046-1205
Bootstrap cache classes
Bootstrap hydrates seeded dashboard data in aggregate responses. Its cache classes are explicit URL shapes and named key tiers rather than guesses based on missing credentials. Fast and slow tiers serve common startup data. On-demand keys serve optional panels and large datasets only when a client asks for them. A small public shape is allowed only when the URL proves that the response has no user variation.
Missing or malformed seed data is returned in the missing list. A Redis or storage failure returns a retryable 503 for public bootstrap instead of a cacheable empty bundle. Credentialed user and desktop keys use the owner’s entitlement and the correct account budget instead of the anonymous session path.
References: api/bootstrap.js• L349-457 api/bootstrap.js• L469-535 api/bootstrap.js• L541-659 api/_user-api-key.js• L516-569
Redis ownership
Shared Redis stores contain both seeder-owned keys and route-owned keys. The route names that ownership when it reads: most monitoring and bootstrap values are read raw because seeders write bare keys, while route-owned snapshots use the deployment namespace. This prevents preview routes from reading production-owned data or missing rows that seeders write.
This rule also applies to product facts, brief pointers, health snapshots, API-key validation, and MCP analysis reads. Health and MCP readers use the same ownership decision so a result and its freshness report cannot come from different namespaces.
References: api/product-catalog.js• L66-90 api/…/share-url.ts• L216-225 api/…/analysis-tools.ts• L146-200 api/health.js• L126-169
Brief routes
Brief lifecycle
Brief routes deliver a composed daily issue in several forms. The dashboard reads a preview and receives a signed magazine URL. A Pro user can create a short-lived public share pointer. Public readers receive a redacted view, while notification channels receive image pages.
The routes read brief records created by a background digest process. They do not compose the issue. A signed reader URL is the sole credential for the magazine route. The latest-brief preview can follow the newest pointer or a valid requested slot, then signs the matching magazine URL for the user. A short retry handles a transient storage timeout, while a real storage failure returns a retryable 503 instead of appearing as an expired or composing brief.
flowchart TD
A[Composed brief envelope] --> B[Latest brief preview]
A --> C[Signed magazine URL]
C --> D[Optional share pointer]
D --> E[Public redacted brief]
A --> F[Carousel image pages]
| Route | Audience | Main output |
|---|---|---|
/api/latest-brief | Authenticated Pro dashboard | JSON preview and signed magazine URL |
/api/brief/{userId}/{issueSlot} | Holder of a signed URL | Personalized HTML magazine |
/api/brief/share-url | Authenticated Pro user | Public share URL for an existing issue |
/api/brief/public/{hash} | Holder of a share hash | No-index public HTML mirror |
/api/brief/carousel/{userId}/{issueSlot}/{page} | Notification delivery | PNG cover or story page |
Brief URLs act as credentials. The signed URL binds a user to an issue slot. A public share link uses a separate hash and exposes only the public rendering. A missing requested slot reports that slot rather than implying that the current issue is still composing. Successful public renders may use a short shared cache, while missing, unavailable, or failed image pages stay private and no-store.
References: api/latest-brief.ts• L1-24 api/latest-brief.ts• L76-96 api/latest-brief.ts• L237-340 api/…/[issueDate].ts• L172-238 api/…/share-url.ts• L168-231 api/…/[hash].ts• L1-19 api/…/[page].ts• L1-24
Brief enrichment
Internal brief enrichment adds a short explanation of why a composed story matters. A trusted relay sends a bounded story record. The route can use analyst context and a fast language-model path. Valid output is cached by a versioned story identity.
References: api/…/brief-why-matters.ts• L1-35 api/…/brief-why-matters.ts• L115-125 api/…/brief-why-matters.ts• L364-425
Search and feed routes
Search services
Search routes turn a user query into a bounded result set. Symbol search supports watchlist typeahead without paid access. Intelligence search covers external documents, filings, history, claims, and similar events. The search layer limits result size and protects shared provider capacity with short-lived cache and cooldown behavior.
Symbol search returns a stable { results } shape. It caches empty results so repeated typing does not multiply provider work. Bad input is a client error. Provider failure and quota exhaustion are retryable service errors.
References: api/symbol-search.ts• L1-10 api/symbol-search.ts• L41-71 api/symbol-search.ts• L124-155 api/symbol-search.ts• L237-339
Feed delivery
Feed routes bring source data into dashboard and partner surfaces. News digest data uses a domain RPC. RSS, X, Telegram, and newsletter feeds use dedicated edge paths because they need source allowlists, relay fallback, normalization, or credential-aware cache rules.
RSS accepts only listed feed domains and approved redirects. The proxy bounds the response by size and item count, then returns XML as non-document text. X and Telegram bodies require an attributable session or key and use private caching. Relay failures preserve the difference between a timeout, a dropped connection, and an upstream application error. Newsletter output is rendered as RSS only when upstream extraction is non-empty.
References: api/rss-proxy.js• L251-375 api/rss-proxy.js• L416-439 api/x-feed.js• L185-280 api/telegram-feed.js• L244-303 api/_relay-failure-level.js• L23-43
Embed and widget routes
Embed entitlement
The embed entitlement route is the authorization bootstrap for a partner iframe. It evaluates the embedding account’s API key, not the viewer’s cookies or anonymous session. This keeps the panel decision tied to the account allowed to embed it.
The route accepts GET and OPTIONS, applies CORS and an endpoint rate limit, and returns private no-store JSON.
References: api/…/entitlement.ts• L1-23 api/…/entitlement.ts• L33-69
Embed session grant
The embed session route exchanges a partner key for a short-lived panel-scoped grant. The frame uses the grant for later map reads, so the long-lived partner key does not travel on every poll. The grant remains tied to the embedding account rather than the page visitor.
References: api/…/session.ts• L1-12 api/…/session.ts• L33-71
Embed map frame
The map-frame route gives a partner map one bounded read instead of several anonymous domain calls. It combines selected monitoring layers and reports per-layer state, so a partner can show available or unavailable data without exposing source controls.
One exact public layer shape can use shared hourly caching. All other requests are private. A valid map grant can unlock the keyed tier, while partial or unavailable source data forces private handling.
References: api/…/map-frame.ts• L1-23 api/…/map-frame.ts• L140-200
Widget agent
The widget-agent route gives an embedded or first-party client a controlled path to the agent service. GET checks relay health. POST forwards an agent request as an SSE stream. The edge validates access, rate, body size, and daily model allowance, then inserts relay secrets on the server side.
References: api/widget-agent.ts• L229-283 api/widget-agent.ts• L287-299 api/widget-agent.ts• L444-568
Analyst chat
The analyst chat route gives Pro users a first-party streaming answer grounded in current WorldMonitor context. It sends source and degradation markers before answer text. It can also send bounded view actions that let the client open a related panel.
The route validates and sanitizes the query and short history before retrieval. A fail-closed rate limit and account daily allowance protect direct language-model work. The allowance is reserved only after input checks and is rolled back when no answer content is served, except when a provider has accepted the request.
References: api/chat-analyst.ts• L147-228 api/chat-analyst.ts• L230-296 api/chat-analyst.ts• L335-379
MCP interfaces
WorldMonitor MCP
The WorldMonitor MCP endpoint adapts monitoring products to the Model Context Protocol. It exposes tools, prompts, resources, skills, UI shells, and discovery metadata through one protocol surface. An AI client can discover a task, call a bounded operation, and receive freshness, coverage, attribution, and access information with the result.
The catalog groups tools into markets and economy, energy, geopolitical security, movement and infrastructure, environment and science, health, humanitarian displacement, AI intelligence, trade and tariffs, and server utilities. One shared category map drives the domain summary, generated discovery documents, and each server-card tool preview. Registry entries connect these tools to data views or REST paths and describe their access class, input contract, and output limits.
Cache-backed tools expose bounded product snapshots with declared freshness checks. The same freshness assessment used by health reads marks missing metadata or source errors as stale. Deployment grace applies only when a marker was read and proves that a producer has never published; an unread or failed marker read does not grant grace.
The catalog includes cache-backed product snapshots such as strategic reservoir levels. That tool presents NASA ICESat-2 lake-level measurements for a watchlist, with country, status, reservoir, and optional series filters. Its status describes water-level conditions; it does not describe storage volume.
Orbital Watch adds paid tools for point satellite passes, country evidence, and watched-site imagery. The site views return the newest archive image, the next predicted imaging pass, and the credit lines needed to cite the images. The point view groups passes into evidence tiers and caps the number shown while retaining counts for omitted passes. The same feature stays unavailable until the orbital service is enabled, so clients see the product’s normal dark-launch response rather than partial data.
The analysis tools turn seeded feeds into convergence, focal-point, cascade, exposure, and activity views. Cache-backed tools expose bounded market, conflict, safety, forecast, climate, and other product snapshots. NLP tools add event classification, entity extraction, topic clustering, claim coverage, and keyword-spike views. A travel-risk assessment tool combines government advice, security, hazards, health, access, aviation, and outage sources into a sourced draft for an analyst to finish. It accepts itinerary data only and keeps unavailable inputs distinct from empty findings. The catalog also marks a small anonymous free set, account allowance reads, and tools that can open a paid panel.
The source inventory is a credential-free registry read that helps an agent judge the provenance of other results. It keeps upstream providers separate from named outlets because hosts describe fetch and licensing obligations, while outlets describe editorial tier, risk, perspective, and platform identity. A summary is available by default; bounded provider or outlet views support filtering without pretending that the two populations are one list.
References: api/…/domains.ts• L1-11 api/…/domains.ts• L14-44 api/…/server-card-tools.ts• L1-30 api/…/discovery-documents.generated.ts• L1-7 api/…/index.ts• L40-58 api/…/_orbital.ts• L165-233 api/…/_orbital-site-imagery.ts• L41-102 api/…/source-tools.ts• L127-159 api/…/source-tools.ts• L163-239 api/…/_source-providers.generated.json• L1 api/…/cache-tools.ts• L3382-3425 api/…/travel-risk-tool.ts• L450-508 api/…/_reservoir-levels.ts• L1-96 api/…/freshness.ts• L16-121 api/…/types.ts• L101-188
Country view tools
The country view gives an AI host an interactive, paid country brief without placing the full brief in the tool result. The open operation selects a country and topic, then returns a scoped panel admission that lets the embedded view load its sections progressively. A second operation reads one named section at a time across risk, economy, resources, trade, infrastructure, signals, and other country data.
Section reads return ready, locked, or unavailable. The state keeps missing or stale evidence distinct from an empty finding. Raw signal reads require a verified panel for the same country, and source records retain their scope, capture time, and attribution.
References: api/…/country-view.ts• L162-193 api/…/country-view.ts• L196-229 api/…/country-view.ts• L263-361
MCP access and protocol
MCP separates discovery from data access. Protocol metadata, tool catalogs, prompt and skill reads, UI shells, public freshness resources, and logging acknowledgements do not require a paid entitlement. A small registry-defined tool set can return free data without a credential, but it still uses a tighter IP limit. Other data tools require a resolved account or operator key. OAuth bearer access and dashboard API keys resolve to the same account budget and owner identity.
The server card and generated guide describe the same hosted endpoint and tool domains as the live registry. The well-known discovery document is cacheable only on its dedicated shape. Its response varies on content negotiation, origin, protocol version, and replay headers so a discovery body cannot be served to a transport client. The live /mcp guide and JSON-RPC responses remain no-store. Old host aliases redirect to the canonical transport rather than acting as separate servers.
The server negotiates the supported MCP protocol versions, including the current 2025-11-25 floor and older compatible versions. A separate 2026-07-28 modern era is enabled per request rather than added to the initialize set. It serves JSON-RPC over streamable HTTP, with SSE framing and bounded replay for eligible authenticated sessions. Replay buffers bind to the authenticated principal and use bounded session, owner, and total storage; anonymous callers can receive a live stream but cannot use a shared replay bucket. Plain discovery documents can be cached only on their dedicated discovery shapes; live protocol responses remain no-store. An anonymous handshake on the transport can challenge the client, while well-known aliases keep a public discovery path. Generic HTTP clients retain a direct stateless path for legacy catalog and free-tool calls.
Per-minute limits are separate from daily allowance. Free data calls fail closed when the limiter or trusted edge-IP proof is unavailable. Paid callers use a plan or account burst budget, while API-tier MCP traffic can share the REST daily meter. Denials retain a structured reason, next step, and upgrade link so an agent can choose between re-authentication, retry, and plan upgrade. The travel-risk tool adds a plan-feature check before execution, so only accounts with that entitlement can use it.
References: api/…/constants.ts• L1-85 api/…/constants.ts• L105-131 api/…/discovery-documents.generated.ts• L1-7 api/…/handler.ts• L696-830 api/…/handler.ts• L1215-1359 api/…/auth.ts• L445-547 api/…/auth.ts• L691-817 api/…/index.ts• L51-67 api/…/types.ts• L392-468
MCP upgrade flow
The MCP upgrade flow turns an eligible access denial into a browser checkout handoff. A user-bound caller can request the next self-serve plan and receive a secure checkout URL. Payment still happens in the browser through the existing billing service, so the MCP route does not collect payment details or create a second billing path.
The response keeps customer states separate. An active subscription points to billing management, a pending payment asks the user to finish the existing checkout, an invalid plan is a client error, and a relay failure is retryable. Hosts that do not allow commerce promotion receive plan information without the checkout tool or purchase prompt.
References: api/…/checkout.ts• L1-11 api/…/checkout.ts• L34-84 api/…/upgrade.ts• L23-111 api/…/host-policy.ts• L65-120
MCP dispatch and response shaping
MCP dispatch validates tool arguments before it reserves allowance. It then reads a cache or calls an approved domain route, evaluates freshness, applies filters, and limits the serialized result. Read failures stay distinct from valid empty data, so a source outage cannot look like no events.
The common result path supports summary mode, projection, attribution, output budgets, spoken summaries, and structured content. Tool metadata also advertises access class, cost weight, output schema, annotations, and optional UI links. Aliases preserve older tool names while directing calls to current tools. Safe downstream error codes cross the tool-fetch boundary without exposing raw response bodies. Billing, quota, validation, source, and output-budget failures remain distinct. Results that use the reservoir projection follow the same REST normalizer as the climate route. Travel-risk execution returns both a Markdown draft and structured content with source status and capture times.
Quota reservation is part of dispatch rather than a background task. Dedicated MCP plans count calls, API plans can count weighted work against the shared REST allowance, and enterprise members can draw from an account pool. Once a tool starts, its slot remains charged because the upstream work has already been performed.
flowchart LR
A[MCP request] --> B[Bounded body read]
B --> C[Method and credential resolution]
C --> D[Entitlement and rate checks]
D --> E[Argument validation and alias resolution]
E --> F[Allowance reservation]
F --> G[Cache read or domain call]
G --> H[Freshness, filters, projection, and output budget]
H --> I[Structured JSON-RPC or SSE response]
References: api/…/dispatch.ts• L494-712 api/…/dispatch.ts• L1074-1134 api/…/dispatch.ts• L1175-1320 api/…/index.ts• L71-103 api/…/_orbital-site-imagery.ts• L81-94 api/…/_reservoir-levels.ts• L25-33 api/…/travel-risk-tool.ts• L450-504 api/…/types.ts• L104-252
MCP panel admissions
Paid country, news, forecast, market, prediction, conflict, disaster, chokepoint, and brief views use a panel admission. The admission is a short-lived signed grant for a bounded group of related reads. Opening or refreshing a view reserves allowance and returns a scoped panel request. Later reads must match the admitted view and scope.
The same admission can be reused for a short window. Uncached reads have a separate bounded read budget. Only usable, fresh responses enter the panel cache. This prevents a panel cache from turning an outage or stale source into a normal result.
References: api/…/panel-requests.ts• L20-49 api/…/panel-requests.ts• L120-149 api/…/panel-requests.ts• L229-341
MCP resources, prompts, skills, and apps
MCP resources have two tiers. Concrete public resources expose anonymous freshness metadata. Data-bearing URI templates route through the same dispatch path as tools/call, so authentication, quota, telemetry, freshness, and output rules stay symmetric across both interfaces. Account allowance resources report a user’s current budget without spending it.
Prompts and skills describe reusable workflows. UI resources provide static, data-free shells that load live results through the host. The news dashboard and related views declare a narrow content policy for the WorldMonitor asset host and map tile hosts. This keeps discovery separate from data access and keeps the MCP Apps handshake, content policy, source links, panel usage, and error display consistent across views.
References: api/…/index.ts• L1-40 api/…/index.ts• L1-24 api/…/index.ts• L1-40 api/…/shell.ts• L1-36 api/…/handler.ts• L1181-1205 api/…/handler.ts• L1485-1582 api/…/types.ts• L696-738
MCP OAuth authorization
MCP OAuth connects an external client to an operator API key or a user’s durable Pro MCP grant. Registration stores an approved client and redirect set. Authorization binds a short-lived consent nonce to the browser, then issues a one-time code. The token route exchanges that code with PKCE and rotates refresh tokens.
Refresh recovery treats a temporary storage or entitlement failure as retryable instead of consuming a usable token. A later or cross-client reuse remains a real replay and revokes the token family. Authorization metadata derives its issuer and endpoint origin from a validated request host. Client metadata is accepted only from a trusted URL set or approved connector prefix.
References: api/…/register.js• L104-180 api/…/authorize.js• L283-389 api/…/token.ts• L621-804 api/…/_refresh-recovery.ts• L1-64
Agent discovery protocols
The route family also provides small anonymous discovery surfaces for clients that do not start with MCP. The NLWeb /ask route ranks public tool descriptions and can return a compact SSE stream. The A2A /a2a route accepts JSON-RPC messages that suggest MCP tools or report public freshness. Neither route reaches gated data or creates a long-running task.
The documentation MCP facade and Agent Skills importer help an agent find the main product paths without becoming alternate data gateways. The documentation facade normalizes malformed JSON-RPC and protocol-level tool errors while keeping real tool failures in MCP tool results.
References: api/ask.ts• L1-13 api/a2a.ts• L1-19 api/docs-mcp.ts• L1-15 api/docs-mcp.ts• L253-330 api/…/fetch-agentskills.ts• L8-35
MCP proxy
The MCP proxy connects an authenticated Pro or authorized desktop caller to a remote MCP server. It supports streamable HTTP and older SSE transport. It validates the remote URL before each outbound request, bounds body and JSON depth, limits redirects, pins the vetted address, and avoids forwarding credentials across an origin change.
The proxy returns remote tool lists and results without turning the remote server into a WorldMonitor data source. Remote authentication failures and protocol responses remain caller-visible. Timeouts, caller-level remote refusals, and proxy defects use separate status and telemetry signals.
References: api/mcp-proxy.ts• L40-74 api/mcp-proxy.ts• L316-347 api/mcp-proxy.ts• L528-611 api/mcp-proxy.ts• L987-1166
Product capability routes
Product catalog
The product catalog supplies public pricing and plan facts for web and machine clients. It uses live payment-provider prices when available and falls back to generated product facts when the provider is unavailable. The response identifies its source so clients can distinguish current data from fallback data.
The catalog describes Free, Pro, Pro Business, API Starter, API Business, and Enterprise plan families. It includes feature limits such as API burst and daily allowance, MCP allowance, direct AI allowance, and desktop-key limits. These facts support product choice and do not replace the gateway’s live entitlement decision.
References: api/product-catalog.js• L42-63 api/product-catalog.js• L217-254 api/_product-catalog.generated.js• L5-45 api/_product-catalog.generated.js• L244-414
Checkout and billing access
Checkout session creation starts a paid product purchase for an authenticated user. The edge route validates the Clerk bearer token and relays a bounded request to the billing service, which owns product, return URL, customer, and pending-payment checks. It does not create the payment session itself.
The customer portal route returns a safe billing destination for a signed-in user or a short-lived email action. Both purchase and portal writes use user-scoped limits and idempotency so retries do not create duplicate billing work. Responses preserve separate meanings for invalid products, active subscriptions, payment in progress, relay failures, and provider failures.
References: api/create-checkout.ts• L127-177 api/create-checkout.ts• L217-297 api/customer-portal.ts• L78-147 api/customer-portal.ts• L182-244
Credentials and account actions
Key routes let a signed-in account create durable credentials for programmatic API access or partner embeds. API keys can carry scopes and can identify API or desktop use. Embed keys also check the current plan and allowed origins. Revoking a key can invalidate its edge cache entry after ownership is checked.
Account routes also sync user preferences, return a privacy-safe referral code and share URL, and reserve bounded passkey offers. These routes keep account data private. A referral binding is best effort so a slow account service does not turn a normal page load into a site-wide error.
References: api/_user-api-key.js• L87-135 api/invalidate-user-api-key-cache.ts• L42-109 api/user-prefs.ts• L111-180 api/…/me.ts• L80-160
Notifications and partner operations
Notification routes manage account delivery channels and rules. They support email, webhook, browser push, quiet hours, digest settings, country and ticker scope, and chokepoint scope through an authenticated relay. Idempotency protects retries that could create duplicate delivery work. Webhook registration checks URL form and DNS results. Stored webhook data is encrypted, while a new signing secret is returned only once.
OAuth binding connects Slack or Discord to the browser that started the flow. Shipping v2 provides partner-facing route intelligence and webhook operations with account-owned integrations. The publish route accepts bounded user events after entitlement, rate, payload, and field-safety checks.
References: api/notification-channels.ts• L435-567 api/notification-channels.ts• L658-929 api/channel-oauth-bind.ts• L19-71 api/notify.ts• L100-219 api/…/[subscriberId].ts• L52-177
Session and desktop capabilities
Browser bootstrap routes establish short-lived anonymous session cookies and hydrate seeded monitoring data. Public bootstrap shapes can use shared CDN caching only when the URL proves that the response has no user variation. Credentialed, session, and entitlement reads remain private.
Desktop sign-in lets a desktop app use a signed-in browser without exposing a browser session to the local app. A separate desktop-key status route tells a self-hosted sidecar whether its wm_ key is active, lapsed, over its key cap, or not a desktop key. It returns a verdict without exposing account identifiers or charging a premium data meter.
References: api/bootstrap.js• L359-457 api/bootstrap.js• L497-535 api/wm-session.js• L171-289 api/…/status.ts• L104-212
Operational health routes
Public health
The public health route reports whether seeded data used by the product is fresh and usable. A compact form supports frequent browser and uptime polling. A detailed form requires an operator or enterprise API key. Health responses stay private and no-store. A last-known verdict can be marked stale when a refresh cannot finish in the edge time budget.
Health grades seed age, coverage, data shape, active release rules, and source state. The health and seed-health surfaces use the same risk input policy and cache-key vocabulary as MCP readers.
References: api/health.js• L126-214 api/health.js• L243-287 api/_cii-input-health.js• L1-20 api/_cii-risk-cache-keys.js• L1-9
Analytics health
The analytics-health route accepts only small anonymous counter reports from the browser collector. It aggregates counts by cohort and time window, then alerts operators only when a failure rate is both well measured and above that cohort’s normal level. It does not accept event payloads, user IDs, URLs, or browser fingerprints.
The route rejects stale or oversized reports and fails closed when its rate-limit or aggregate store cannot protect the signal. A successful write returns 204; an unavailable aggregate is a retryable 503.
References: api/analytics-health.js• L1-10 api/analytics-health.js• L143-195 api/analytics-health.js• L466-509
Operations and cache control
Operational routes support liveness, runtime-mode reads, cache invalidation, security-report intake, notification suppression reads, and other internal control tasks. Cache purge requires the relay secret and accepts only bounded explicit keys or suffix patterns. It protects authentication, replay, connector, webhook, desktop, and durable product keys.
Some control reads fail open for the client feature. For example, notification suppression returns an unavailable marker so a service worker can continue navigation when Redis cannot be read. Security reports are reduced to safe metadata before logging.
References: api/cache-purge.js• L9-27 api/cache-purge.js• L93-194 api/correlation-runtime-mode.js• L30-97 api/notification-suppressions.js• L1-24 api/…/report.js• L100-135
Response behavior
Status contracts
HTTP status describes request and service state. Successful domain responses can also carry freshness or availability fields when a source is partial. Validation failures return 400. Authentication and entitlement failures return 401 or 403. Provider and internal service failures return retryable 502 or 503 when the caller should try again.
| Condition | Usual response | Client action |
|---|---|---|
| Invalid request fields, JSON, or body size | 400 or 413 | Fix or reduce the request |
| Missing or invalid credential | 401 | Authenticate or refresh the credential |
| Valid caller without the required plan | 403 | Change plan or use an allowed route |
| Rate limit or quota reached | 429 with Retry-After | Back off until reset |
| Rate-limit or verification service unavailable | 503 with a degraded marker | Retry; do not treat it as an empty dataset |
| Upstream or verification service unavailable | 502 or 503 | Retry and do not treat it as an empty dataset |
| Unknown route or wrong method | 404 or 405 | Check path and method |
Some generated RPCs retain typed error information inside HTTP 200 for compatibility. External protocols keep their own JSON-RPC or OAuth error envelopes while preserving the same retry and no-store meaning. MCP source failures use a structured unavailable error with retryable, stale, unavailable-input, and failed-input fields. Invalid tool arguments keep field-level violations. Output that exceeds a tool budget returns an actionable bounded result instead of an unbounded payload.
References: api/_rate-limit.js• L152-269 api/_relay.js• L34-55 api/…/dispatch.ts• L1430-1457 api/…/_orbital-site-imagery.ts• L81-89 api/…/travel-risk-tool.ts• L177-199
Freshness and projection
GET responses use route-specific freshness tiers. Public shared reads can use a CDN cache only when their path and query match an allowlisted public shape. Credentialed, premium, account-private, live, degraded, and unavailable responses are private or no-store. Cacheable JSON GETs can receive ETags and 304 responses.
MCP cache reads apply the declared freshness checks to fetch time, source state, record counts, content age, and producer content-freshness data. They expose an explicit stale or pending state instead of treating missing freshness evidence as a current result. This keeps MCP freshness decisions aligned with the health surface.
Clients can add jmespath to request a smaller JSON view. MCP applies the same projection and output limits. REST reports a projection error as 400. MCP returns a bounded soft result inside its JSON-RPC response. Licensed MCP results retain attribution after projection. Successful MCP calls also carry structured content for clients that validate the advertised output schema.
References: server/gateway.ts• L2057-2181 server/…/response-projection.ts• L3-16 api/…/constants.ts• L120-135 api/…/freshness.ts• L24-121 api/…/dispatch.ts• L1175-1320
Markdown URL twins
Markdown URL twins give agents a text representation of a page without creating a second API data source. The twin resolves only a same-origin sibling, follows a bounded redirect chain, converts HTML or JSON to bounded markdown, and marks missing or failed documents as no-store and noindex.
References: api/_md-url-twin.ts• L1-18 api/_md-url-twin.ts• L48-85 api/_md-url-twin.ts• L324-487
Change checklist
When these files or sections are changed, remember to consider these:
- When adding or changing a domain RPC, keep its service contract, generated route, handler mapping, request validation, public description, and gateway cache tier aligned.
- When changing Orbital Watch routes or tools, keep the generated service contract, gateway entry point, dark-launch response, MCP publication state, paid access, site filters, freshness meaning, and image credits aligned.
- When changing a public response, update the exact path-and-query allowlist and verify that credentialed requests cannot enter the public cache shape.
- When changing CORS or client-IP handling, keep origin allowlists, transit proof, trusted peer ranges, rate-limit identifiers, and exposed retry headers aligned.
- When changing account API limits, keep catalog plan facts, per-minute burst rules, daily REST/MCP sharing, meter rollback, response headers, and gateway enforcement aligned.
- When changing a feed relay, preserve origin checks, allowlisted hosts and redirects, credential-aware caching, normalization, byte limits, timeout, and upstream error behavior.
- When changing brief URLs or issue slots, keep signing, share pointers, TTLs, public rendering, telemetry-only enrichment, success-only caching, and carousel lookup aligned.
- When changing latest-brief lookup or retry behavior, keep pointer and slot validation, composing responses, signed URL creation, timeout budgets, and retryable storage errors aligned.
- When changing an MCP tool, keep its registry entry, category, access class, input and output schemas, weight, output budget, REST path crosswalk, UI link, spoken narrator, and generated discovery metadata aligned.
- When changing MCP categories or tool descriptions, keep the category map, server-card projection, generated server card, guide text, and live
tools/listcontract aligned. - When changing MCP discovery or transport behavior, keep the canonical endpoint, alias redirects, discovery
Varyheaders, cacheability, no-store policy, negotiated versions, session ownership, and SSE replay limits aligned. - When changing MCP freshness rules, keep cache-tool checks, content-age assessment, activation-marker reads, health grading, stale output, and pending deployment grace aligned.
- When changing source inventory data, keep provider and outlet populations separate, preserve license and provenance fields, and keep summary counts consistent with filtered views.
- When changing country view sections, keep section schemas, same-country panel admission,
ready/locked/unavailablemeanings, attribution, and bounded source reads aligned. - When changing MCP tools that reuse a REST data view, keep the shared normalizer, filter meaning, freshness key, coverage check, output schema, and REST crosswalk aligned. This applies to reservoir levels.
- When changing the travel-risk assessment, keep the plan-feature flag, source list, input limits, source freshness, unavailable meanings, structured output, Markdown output, and allowance weight aligned.
- When changing MCP filters or validation, keep advertised schemas, runtime checks, bounds, and quota reservation order aligned.
- When changing MCP authentication or access classes, keep bearer grants, dashboard-key ownership, free-tool promotion, per-user or account burst limits, internal downstream signing, and usage identity aligned.
- When changing MCP allowances, keep plan facts, shared REST counters, enterprise account pools, allowance reads, denial data, and reset behavior aligned.
- When changing MCP protocol or discovery behavior, keep the negotiated version set, modern envelope and headers, server card, public methods, resource lists, skills, OAuth metadata, replay ownership, canonical aliases, cache
Varyrules, and no-store behavior aligned. - When changing MCP downstream calls or proxy behavior, keep safe error mapping, credential forwarding, redirect rules, body limits, timeout classes, and caller-visible protocol errors aligned.
- When changing OAuth, keep host allowlists, redirect allowlists, trusted client metadata, PKCE, browser binding, one-shot state, grant ownership, refresh recovery, and replay evidence aligned.
- When changing checkout, billing portal, referral, or account relays, keep bearer validation, user and IP limits, idempotency scope, ownership checks, return URL policy, and no-store behavior aligned.
- When changing notifications or shipping webhooks, keep entitlement gates, owner binding, encrypted secrets, compare-and-set updates, durable delivery state, and validation error passthrough aligned.
- When changing health or analytics health, keep input coverage, freshness grades, compact projections, snapshot fallback, rate-limit posture, and stale or unavailable meanings aligned.
- When changing cache purge or control reads, keep blocklists, durable-key protection, query shape, fail-open or fail-closed behavior, and client fallback meaning aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A domain path lacks a generated route or handler mapping | The gateway returns 404 or 405 for a known client operation | Keep generated route factories and gateway mapping together |
| Orbital Watch is called while its feature flag is off | REST and MCP clients receive a dark 404 instead of a partial orbital result | Keep the shared launch check and uncached dark response on both entry paths |
| A credentialed feed, bootstrap, or embed result receives public cache headers | One caller’s private data can reach another caller | Decide shareability from the URL before auth and use private or no-store caching for user variation |
| An entitlement, rate-limit, or storage service is unavailable | The client sees a false free, empty, or expired state | Return a retryable error and keep uncertain results out of shared cache |
| A public bootstrap URL has an extra or unlisted query key | A combinatorial cache key space can amplify reads or mix response classes | Accept only exact registered public URL shapes |
| A relay timeout is treated as an application defect | Routine upstream latency creates false operator alerts or the wrong client retry behavior | Classify timeouts and established-connection drops separately from connection or application failures |
| A free MCP caller reaches a subscription tool | The caller can bypass the paid data boundary or spend a useless allowance slot | Check the registry access class before reservation and downstream dispatch |
| A requested brief slot is treated as the current latest slot | The dashboard shows a misleading composing state for a missing historical issue | Preserve the requested slot in the composing response |
| A transient brief-store timeout is treated as a missing brief | A healthy brief appears to be composing and hides a retry path | Retry one bounded timeout and return 503 when the store remains unavailable |
| MCP arguments are checked after allowance reservation | Invalid calls spend a daily slot and hide the real client error | Validate resolved arguments before panel or quota reservation |
| The free MCP rate limiter or trusted client-IP proof is unavailable | Anonymous data could become unbounded or share one caller’s bucket | Fail closed with a retryable degraded response |
| A plan-feature check is missing for the travel-risk tool | An account can invoke a paid assessment without the required product feature | Check travelRiskAssessment before allowance reservation and execution |
| A travel-risk source outage is rendered as an empty finding | An analyst may read missing evidence as evidence of no risk | Keep source status unavailable, require at least one usable source, and return structured source reasons |
| Reservoir pass age is used as the freshness verdict | Normal satellite publication delay makes a healthy snapshot look stale | Grade freshness from the seed run and watchlist coverage, not from latest.ageDays |
| MCP reservoir filtering uses a different normalizer from REST | Agents and the dashboard disagree about reservoir fields or filters | Reuse the REST seed normalizer and keep the MCP projection as a view over it |
| A data-bearing resource bypasses tool dispatch | Resource reads can avoid auth or quota | Keep public resources metadata-only and send templates through normal dispatch |
| A projected MCP result loses attribution or freshness caveats | A strict client rejects it or a user sees an unsupported current claim | Reattach attribution and citations after shaping |
A discovery response is cached without its content-negotiation or replay Vary keys | A manifest can be served to a transport client as a false successful handshake | Vary discovery responses on Accept, Last-Event-ID, Origin, and MCP-Protocol-Version |
| An SSE replay cursor is accepted without the owning principal | One caller can read or evict another caller’s buffered tool result | Bind replay sessions to the authenticated owner and give anonymous streams no replay buffer |
| A category is missing for a registry tool | Generated discovery metadata and the live server card disagree about the tool’s domain | Keep the category map complete and fail the generation checks when a tool has no category |
| Freshness metadata or an activation marker is unreadable | MCP can report a current result or grant deployment grace without proof | Treat missing metadata and unread markers as stale or unknown and fail closed |
| A refresh token is consumed before a transient recovery path is stored | A client loses its connector after a normal timeout | Use an atomic attempt marker and bounded same-client recovery |
| A proxy call follows an unvetted redirect or forwards credentials across origins | A remote server can redirect secrets or requests to an internal host | Resolve and pin each target and keep cross-origin headers to a small safe set |
| A security or analytics endpoint accepts raw user content | Operational logs or health alerts become a data or abuse channel | Accept bounded fields and aggregate or summarize before storage |
| A webhook update overwrites a delivery worker’s newer record | Delivery state, ownership indexes, or secrets become inconsistent | Use compare-and-set writes and retry on conflict |
| A cache purge includes OAuth, replay, webhook, or desktop keys | Users are logged out, replay protection resets, or durable tenant data is deleted | Block protected prefixes and durable data from purge |
Key files
| File | Why to read it |
|---|---|
| server/gateway.ts | Defines the shared request pipeline, access gates, rate limits, cache tiers, ETags, projection, and response assembly |
| server/router.ts | Shows route matching and 404/405 behavior |
| api/_cors.js, api/_rate-limit.js, and api/_api-key-rate-limit.js | Define browser origin trust, client identity, degraded limits, account burst limits, and daily API usage |
| api/_user-api-key.js and api/…/status.ts | Show user-key identity, key kinds, entitlement checks, desktop scope, and status verdicts |
| api/bootstrap.js | Shows seeded hydration, public URL classes, cache posture, validation, and auth/cache contracts |
| api/api-route-exceptions.json | Defines deliberate exceptions to the typed JSON API boundary |
| api/…/[rpc].ts, api/…/[rpc].ts, api/…/[rpc].ts, and generated service servers | Show representative versioned domain entries, the orbital dark-launch gate, and service contracts |
| api/latest-brief.ts, api/…/[issueDate].ts, api/…/share-url.ts, and api/…/[hash].ts | Show brief preview, signed access, public sharing, and success-only public caching |
| api/symbol-search.ts, api/rss-proxy.js, api/telegram-feed.js, and api/x-feed.js | Show bounded search and credential-aware feed delivery |
| api/…/entitlement.ts, api/…/session.ts, and api/…/map-frame.ts | Show partner authorization, short-lived grants, and bounded map reads |
| api/widget-agent.ts and api/chat-analyst.ts | Show premium agent streaming, relay protection, grounding, and streaming quota behavior |
| api/…/handler.ts | Shows MCP discovery, authentication, protocol negotiation, resource tiers, JSON-RPC dispatch, and bounded SSE replay |
| api/…/domains.ts, api/…/server-card-tools.ts, and api/…/discovery-documents.generated.ts | Show the shared tool categories and how registry metadata reaches generated and live discovery surfaces |
| api/…/freshness.ts and api/…/types.ts | Show shared freshness decisions and the public contracts for access classes, tool schemas, budgets, and resources |
| api/…/index.ts, api/…/_orbital-site-imagery.ts, and api/…/cache-tools.ts | Show registry composition, access classes, the watched-site imagery tool, cache tools, freshness rules, and REST crosswalks |
| api/…/_orbital.ts, api/…/country-view.ts, api/…/source-tools.ts, and _source-providers.generated.json | Show bounded orbital passes, country panel sections, and separate provider and outlet provenance views |
| api/…/travel-risk-tool.ts and api/…/_travel-risk-document.ts | Show itinerary limits, source-backed travel assessment output, plan-feature access, and unavailable-source meaning |
| api/…/_reservoir-levels.ts and server/…/list-reservoir-levels.ts | Show the shared reservoir normalizer, filters, statuses, series projection, and output contract |
| api/…/quota.ts and api/…/upgrade.ts | Show daily allowance ownership, shared REST metering, structured denial reasons, and upgrade attribution |
| api/…/panel-requests.ts | Shows data reads, freshness, scoped panel admissions, and bounded budgets |
| api/…/authorize.js, api/…/register.js, api/…/token.ts, and api/…/_refresh-recovery.ts | Show client registration, browser consent, PKCE exchange, refresh rotation, and retry recovery |
| api/product-catalog.js, api/_product-catalog.generated.js, and api/create-checkout.ts | Show public product facts, generated plan limits, fallback pricing, and billing-session relay |
| api/notification-channels.ts, api/channel-oauth-bind.ts, api/notify.ts, and shipping webhook routes | Show account delivery settings, provider binding, publish safety, and partner webhook ownership |
| api/health.js, api/analytics-health.js, api/correlation-runtime-mode.js, and api/cache-purge.js | Show public freshness status, collector health, runtime controls, stale fallback, and protected cache invalidation |
| api/docs-mcp.ts, api/…/fetch-agentskills.ts, and api/mcp-proxy.ts | Show anonymous agent discovery, docs protocol adaptation, skill import, remote MCP access, and proxy usage records |