` landmarks for screen readers * **Layer**: Subtle copy, integration category pills, remaining slate captions on the [Layer marketing site](https://axiomlayer.io), and the benchmark-card note on the free [shadow IT scan](/layer/integrations/google-workspace) all now clear WCAG AA contrast. Visual hierarchy is unchanged * **Layer**: The in-product login and signup pages now expose a proper `

` landmark, and the primary sign-in button and signup link use a deeper indigo that clears WCAG AA contrast on white. Visual hierarchy is unchanged * **Locus**: Pricing page now meets WCAG AA contrast across muted copy, the **BEST VALUE** badge, and tier-card text, with a proper `

` landmark and corrected heading order. The fix lifts shared design tokens, so the pulse, docs, and other token-driven pages inherit the contrast improvements automatically. Tier-card body text was further lifted in a follow-up pass, and the **Contact us** link on the Enterprise tier is now underlined so it doesn't rely on color alone to indicate it's a link * **Locus**: All eight content pages on [locus.axiomancer.io](https://locus.axiomancer.io) — blog, pulse, docs, methodology, sources, [explore](https://locus.axiomancer.io/explore), [signals](https://locus.axiomancer.io/signals), and rankings — now expose a proper `

` landmark, so screen readers can jump straight to the primary content and Lighthouse `landmark-one-main` audits pass site-wide * **Locus**: Shared content footer on [pricing](https://locus.axiomancer.io/pricing), [blog](https://locus.axiomancer.io/blog), [pulse](https://locus.axiomancer.io/pulse), [docs](https://locus.axiomancer.io/docs), and the rest of the token-driven content pages now meets WCAG AA contrast across column headings, body copy, copyright, and the **Privacy** / **Terms** links * **Locus**: Category pills on the [Locus blog](https://locus.axiomancer.io/blog) now use deeper indigo, green, and yellow shades so labels clear WCAG AA contrast on the light card background, including a follow-up bump on the **Market Intelligence** pill to push its green tone the rest of the way past AA. The pill colors still read as the same color family — only the saturation was lifted * **Overwatch**: Checkout buttons on the [Overwatch pricing page](https://axiomoverwatch.io/pricing) now render dark label text on the amber Professional and cyan Supply Chain Risk tiers, lifting both buttons well past WCAG AA contrast * **Overwatch**: The [Overwatch blog](https://axiomoverwatch.io/blog) index and individual posts now expose a proper `

` landmark and lift de-emphasized slate copy past WCAG AA contrast on the dark background, so screen readers can jump straight to the post body and Lighthouse audits pass * **Overwatch**: Final marketing-site contrast lifts on [axiomoverwatch.io](https://axiomoverwatch.io) — newsletter footer text, hero stat labels, and the blog publications input placeholder and "view all" link all now meet WCAG AA contrast on the dark background, clearing the remaining color-contrast violations on the homepage and `/blog` embeds * **Overwatch**: Final a11y sweep across the in-product routes — [live map](/overwatch/getting-started), [ports](https://axiomoverwatch.io/ports), compare, congestion monitor, intelligence, and trade-intelligence pages all lift their remaining slate copy past WCAG AA contrast, so secondary labels, vessel-marker tooltips, and dashboard previews are now legible on the dark background * **Overwatch**: The [platform page](https://axiomoverwatch.io/platform) now exposes a `

` landmark, fixes heading order under **Live products**, **Coming Q3**, and **Who uses Overwatch**, and lifts de-emphasized slate copy past WCAG AA contrast on the dark background * **Layer, Locus, Overwatch**: Brand colors and **Docs** link fallbacks aligned across all four sites — pink for Layer, indigo for Locus, with the Docs link falling back to each product's own docs section * **Platform**: The [Axiomancer Labs landing page](https://axiomancer.io) now exposes a **Docs** link in its top nav and footer, lifts solid-button labels past WCAG AA contrast, and aligns its cross-product bar accents with the refreshed Layer pink and Locus indigo palette * **Platform**: The [Axiomancer Labs landing page](https://axiomancer.io) no longer flips into Next.js's error fallback on first load, so the home page renders with its proper `lang` attribute and `

` landmark every time. A safety net was also added so the fallback page itself stays accessible if any provider throws — clearing remaining Lighthouse `html-has-lang`, `landmark-one-main`, and `errors-in-console` audits No action is required on your part for any of the fixes above. # April 25, 2026 (/changelog/2026-04-25) ## Service status page [#service-status-page] Overwatch now ships with a built-in [status page](/overwatch/status-page) that surfaces real-time health for core platform services — database connectivity, AIS data freshness, and pipeline health. Each service shows operational, degraded, or down with a 24-hour visual timeline, and a programmatic `/api/health` endpoint is available for external monitoring tools. Health checks run every five minutes. ## Wider AIS coverage and tiered retention [#wider-ais-coverage-and-tiered-retention] Default vessel tracking radius around each monitored port has expanded from roughly 55 km to 220 km, so in-transit vessels appear on your map well before reaching anchorage. A global AIS mode is also available for use cases like dark fleet detection and open-ocean STS monitoring. Position history now follows a tiered [retention policy](/overwatch/data-retention) — full resolution for the last 7 days, one report per vessel per minute from 7 to 30 days, and full-resolution archives beyond that. See [AIS coverage](/overwatch/ais-coverage) for configuration details. ## Redesigned vessel icons and Long Beach hero map [#redesigned-vessel-icons-and-long-beach-hero-map] Vessel markers on the [live map](/overwatch/getting-started) now use elongated, bow-forward triangles that match the silhouette used on VesselFinder and MarineTraffic. Each triangle is colored by vessel type and rotated to heading, so traffic patterns and vessel classes are readable at every zoom level. The default hero map location has also moved from the Bosphorus to the Port of Long Beach. ## Hydrostatic cargo estimates backfilled [#hydrostatic-cargo-estimates-backfilled] Approximately 16,000 departed vessel visits that were missing hydrostatic cargo estimates have been backfilled. If you query historical [cargo validation](/overwatch/methodology/cargo-validation) data, you should see more complete draft and displacement readings for past visits. No action is required on your part. ## More reliable enrichment and risk pipelines [#more-reliable-enrichment-and-risk-pipelines] Several Overwatch backend pipelines were stabilized this week: * [Vessel metadata enrichment](/overwatch/api/vessels) from Equasis now handles concurrent requests instead of queueing serially, eliminating the intermittent timeouts that were causing roughly 120 failed requests per day. Session-renewal retries also fully re-establish the session before re-fetching data. * The daily training-feature job for the [vessel risk score](/overwatch/api/risk) model — including ship-to-ship transfer history and identity-change events — runs cleanly again after a column mismatch was corrected. * Kinematic fingerprint computation now processes vessel visits in parallel chunks, so vessels with large visit histories no longer time out. * The vessel-visits processor uses smaller batches and the [disruptions](/overwatch/api/disruptions) pipeline enforces a 15-second per-query timeout, so port-call timelines and disruption signals stay current through load spikes. * Loitering detection now references the correct timestamp column, improving behavioral anomaly accuracy. * Rate-limited AIS requests are no longer logged as failures, reducing false error noise in pipeline monitoring. ## Cell scoring writes restored and walkability scoring fixed [#cell-scoring-writes-restored-and-walkability-scoring-fixed] Two silent regressions in [cell scoring](/locus/scoring-conventions) were resolved: * The scoring pipeline had been reporting successful runs while writing zero rows — upsert errors were being swallowed rather than surfaced, stalling score updates since around April 22. Scoring now fails loudly on write errors, so cell scores, [rankings](/locus/api/analytics), and queries through the [Locus API](/locus/api/discovery-and-intelligence) are flowing again. * Walkability scores were silently returning null for any cell that wasn't already cached, after the upstream OpenStreetMap data provider began rejecting requests without a User-Agent header. New cells now resolve walkability data correctly, and the [accessibility signal group](/locus/api/overview) reflects the full set of pedestrian-network signals again. ## Faster code enforcement updates [#faster-code-enforcement-updates] Code enforcement data collection was timing out for all monitored cities because the 30-day lookback exceeded processing limits. The collector now uses a 7-day window matching its weekly cadence, so code enforcement records flow into [cell scoring](/locus/scoring-conventions) and the [Locus API](/locus/api/discovery-and-intelligence) without interruption. ## Audit log [#audit-log] Layer now records an immutable audit trail of every significant action in your workspace — integration connects and disconnects, asset changes, role grants and revocations, contract uploads, and more. Each entry captures who performed the action, what was affected, and when it happened. You can view the full log under **Settings → Audit log** and filter by action type or search across entries. Events are retained for six years to support HIPAA and SOC 2 compliance requirements. ## AI spend tracking [#ai-spend-tracking] You can now track per-employee usage and cost across AI tools — including OpenAI, Anthropic, GitHub Copilot, Cursor, Gemini, Perplexity, and RouteShift. Each employee's AI tab shows a breakdown by model, token count, and source so you can understand where AI spend is concentrated and identify optimization opportunities. ## Virtual cards for SaaS spend [#virtual-cards-for-saas-spend] Layer can now issue virtual cards with per-vendor spend caps. Set a hard limit when issuing a card and adjust it on the fly without reissuing — giving finance teams granular control over SaaS purchases. Available under **Spend → Virtual cards**. ## Spend budgets [#spend-budgets] Set monthly or annual spending budgets scoped by department, category, or individual app. The budgets dashboard tracks real-time utilization and alerts you when spend approaches or exceeds the limit. Available under **Spend → Budgets**. ## SaaS benchmarks [#saas-benchmarks] Layer now compares your per-employee SaaS spending against industry benchmarks across categories like cloud infrastructure, developer tools, and HR. The benchmarks page highlights where you're overspending relative to similar organizations and surfaces actionable cost-reduction insights. ## License management and seat harvesting [#license-management-and-seat-harvesting] A dedicated license inventory now shows total versus used seats, renewal dates, and cost per license across your SaaS stack. Built-in seat harvesting identifies inactive users so you can reclaim unused licenses and reduce waste. ## Access reviews [#access-reviews] Launch user access review campaigns that ask employees to confirm which apps they actively use. Configure deadlines, custom messaging, and escalation rules. Completed reviews feed directly into license harvesting and offboarding workflows. ## Access approval workflows [#access-approval-workflows] Define multi-stage approval rules for new SaaS access requests. Approvals can route through manager, IT, security, and finance stages based on cost thresholds, with per-stage notification channels. Available under **Settings → Access approval rules**. ## Contract management with AI extraction [#contract-management-with-ai-extraction] Upload SaaS contracts (PDF or manual entry) and Layer extracts key terms — vendor name, value, renewal date, auto-renewal clauses, and cancellation windows. The contracts page tracks renewal timelines and generates AI-powered recommendations (negotiate, downgrade, cancel, or consolidate) so you can act before deadlines pass. ## Renewal calendar [#renewal-calendar] A dedicated renewal timeline with urgency indicators and notice-period deadlines for auto-renewing contracts. Configure alert settings to get notified before cancellation windows close, and export renewals as CSV or iCal feeds. ## Automated offboarding [#automated-offboarding] When an employee departs — detected via HRIS webhook or triggered manually — Layer runs a revocation pipeline that removes OAuth and SSO access, reclaims licenses, queues device returns, and generates compliance evidence. The offboarding card on each employee's profile shows real-time progress. ## Employee onboarding checklist [#employee-onboarding-checklist] Each new hire's profile now includes a day-one readiness tracker showing which provisioning steps (app access, device setup, account creation) are complete and which are still pending. ## Device shipping [#device-shipping] Ship hardware to employees directly from Layer with carrier tracking and label generation. International shipping includes vendor comparison across Workwize, Hofy, Firstbase, and Allwhere, with customs-hold tracking and cost quoting. ## Compliance readiness dashboard [#compliance-readiness-dashboard] A full compliance control center is now available under **Settings → Compliance**. It shows readiness scoring, coverage and freshness percentages, gap analysis by severity, and lets you search, filter, and sort controls. Evidence tracking is built in, and configurations can be imported or exported as portable presets. ## Webhook notifications [#webhook-notifications] Configure webhook channels under **Settings → Notifications** and route specific events — shadow app detected, renewal approaching, control failing, access review due — to external systems like Slack or PagerDuty. ## Custom fields [#custom-fields] Define custom metadata fields (text, number, boolean, or date) on assets, contracts, apps, controls, and evidence records to tailor the platform to your organization's taxonomy. Available under **Settings → Custom fields**. ## Scheduled reports [#scheduled-reports] Set up recurring CSV or PDF reports for renewals, assets, or apps on a daily, weekly, or monthly cadence. Reports are delivered to a list of email recipients with run-status tracking. Available under **Settings → Reports**. ## Global search [#global-search] A cross-entity search bar now lets you find apps, people, assets, and contracts from a single input. Results are grouped by type with direct links to detail pages. ## MCP server for AI agents [#mcp-server-for-ai-agents] Layer now exposes a Model Context Protocol endpoint that lets AI assistants query your asset inventory, discovered apps, compliance controls, and platform overview counts programmatically. This lets tools like Claude and ChatGPT interact with your Layer data directly. ## Free shadow IT scan [#free-shadow-it-scan] A no-signup scan is now available that connects to [Google Workspace](/layer/integrations/google-workspace) via OAuth, discovers up to 50 shadow IT apps in under five minutes, and generates a shareable risk report. No account required. ## Browser extension for SaaS discovery [#browser-extension-for-saas-discovery] The Axiom Layer Precision browser extension tracks active versus passive SaaS usage and login events on managed devices, syncing real-time app discovery data back to the platform for more accurate shadow IT detection. ## Plan-tier limits now enforced at runtime [#plan-tier-limits-now-enforced-at-runtime] Layer plan limits — employee count, apps shown on free scans, contract AI extraction, and per-minute API and search budgets — are now enforced live across the dashboard and API. Hitting a cap surfaces an in-context upgrade banner instead of failing silently, and `/api` responses include rate-limit headers so you can see your remaining budget. API access is reserved for the **Scale** plan; lower tiers receive a 403 with an upgrade link. See [Plans and billing](/layer/billing) for the full per-tier matrix. ## Dashboard persona setting [#dashboard-persona-setting] You can now switch your dashboard perspective between Finance, IT, or Both under **Settings**, surfacing the metrics and views most relevant to your role. ## Hardware lifecycle settings [#hardware-lifecycle-settings] Configure device depreciation periods, replacement age thresholds, and warranty-expiry requirements under **Settings** to drive automated hardware refresh recommendations. ## Shadow app review queue [#shadow-app-review-queue] Newly discovered shadow apps now flow through a dedicated review queue with an approve/reject workflow and explicit confirmation step, so nothing changes in your inventory until you've reviewed it. ## Refreshed Layer brand accent [#refreshed-layer-brand-accent] Layer's brand accent color has shifted from amber to pink across the [Layer marketing site](https://axiomlayer.io) and dashboard. The cross-product navigation bar at the top of every Axiom site now reflects the updated palette — pink for [Layer](https://axiomlayer.io) and indigo for [Locus](https://locus.axiomancer.io) — keeping product accents consistent wherever you are. Amber is still used to signal warnings like upcoming renewals and alert states, so nothing changes for in-product status indicators. ## Higher-contrast labels in the cross-product bar [#higher-contrast-labels-in-the-cross-product-bar] Inactive product labels in the cross-product bar at the top of every Axiom site now render at a stronger contrast against the dark background, meeting WCAG AA contrast guidelines. Active and hovered states are unchanged. ## Higher-contrast Locus accent in the cross-product bar [#higher-contrast-locus-accent-in-the-cross-product-bar] The active **Locus** label in the cross-product bar at the top of every Axiom site now uses a lifted indigo shade that meets WCAG AA contrast against the dark bar background. The canonical Locus brand color is unchanged everywhere else — this adjustment is scoped to the bar context only, where the previous shade fell just short of the contrast threshold for normal-weight text. No action is required on your part. ## Product-aware Docs link in the cross-product bar [#product-aware-docs-link-in-the-cross-product-bar] The **Docs** link in the cross-product bar at the top of every Axiom site now lands you in the docs section for the product you're currently viewing — Layer, Overwatch, Locus, or Codex — instead of always opening the docs root. If you're on a marketing or shared page with no active product, the link falls back to the docs section for whichever product's site you're on. ## Locus brand colors and Docs fallback corrected [#locus-brand-colors-and-docs-fallback-corrected] The cross-product bar on [locus.axiomancer.io](https://locus.axiomancer.io) now uses the updated indigo accent for Locus and the new pink accent for Layer, matching the refreshed brand identity used elsewhere on the platform. The **Docs** link on Locus marketing pages also now falls back to the [Locus docs](https://docs.axiomancer.io/locus) when no product is active, instead of incorrectly defaulting to the Layer docs. No action is required on your part. ## Overwatch brand colors and Docs fallback corrected [#overwatch-brand-colors-and-docs-fallback-corrected] The cross-product bar on the Overwatch site now uses the updated pink accent for Layer and indigo accent for Locus, matching the refreshed brand identity used elsewhere on the platform. The **Docs** link on Overwatch marketing pages also now falls back to the [Overwatch docs](/overwatch/getting-started) when no product is active, instead of incorrectly defaulting to the Layer docs. No action is required on your part. ## Improved contrast for cross-product bar labels [#improved-contrast-for-cross-product-bar-labels] Inactive product labels in the cross-product bar at the top of every Overwatch page are now easier to read. The label color was lifted to meet WCAG AA contrast requirements against the dark bar background, so links to Layer, Locus, and Codex stay legible for users with low-vision needs. No action is required on your part. ## Higher-contrast Locus accent in the cross-product bar [#higher-contrast-locus-accent-in-the-cross-product-bar-1] The Locus label in the cross-product bar at the top of every Overwatch page now uses a slightly lighter indigo so it meets WCAG AA contrast against the dark bar background. The canonical Locus brand accent is unchanged everywhere else — only the bar context is adjusted to keep the wordmark legible for users with low-vision needs. No action is required on your part. ## Higher-contrast solid buttons on the Layer marketing site [#higher-contrast-solid-buttons-on-the-layer-marketing-site] Solid-fill buttons on [axiomlayer.io](https://axiomlayer.io) — the **Get started** CTA in the navigation bar and the active state on integration category pills — now meet WCAG AA contrast requirements for white text. Previously, the indigo brand accent fell just short of the 4.5:1 threshold for normal-weight text. A stronger indigo is now used for these solid backgrounds, while the canonical brand accent remains in place for highlights, dots, and borders. No action is required on your part. ## Slack integration credentials encrypted at rest [#slack-integration-credentials-encrypted-at-rest] Slack workspace credentials used by Layer's shipping notification integration are now encrypted at rest, matching how every other [integration](/layer/integrations/overview) connection is stored. Existing connections were migrated transparently and continue working without any reconnection. No action is required on your part. ## Stronger ownership checks on virtual card issuance [#stronger-ownership-checks-on-virtual-card-issuance] Layer now verifies that the cardholder belongs to your organization before issuing a [virtual card](/layer/integrations/overview), eliminating a class of cross-tenant errors that could have allowed a card to be issued against another workspace's billing balance. Card issuance flows are unchanged for legitimate users. No action is required on your part. ## Walkability scoring restored [#walkability-scoring-restored] Fixed an issue where walkability scores were silently returning null for any cell that wasn't already cached. The upstream OpenStreetMap data provider began rejecting requests without a User-Agent header, and the [accessibility signal group](/locus/api/overview) — which feeds walkability into [cell scores](/locus/scoring-conventions) — had been quietly degrading as a result. New cells now resolve walkability data correctly, and accessibility scores reflect the full set of pedestrian-network signals again. No action is required on your part. ## Refreshed Locus social previews [#refreshed-locus-social-previews] Link previews and social cards for [locus.axiomancer.io](https://locus.axiomancer.io) now render with the updated Locus identity — indigo accent on a near-black foundation — replacing the off-brand placeholder used previously. Sharing a Locus URL on Slack, LinkedIn, or X will show the new card automatically. The marketing site also serves its primary fonts directly, removing a render-blocking request and reducing the brief flash of unstyled text on first load. ## Improved accessibility on Locus marketing pages [#improved-accessibility-on-locus-marketing-pages] The [Locus homepage](https://locus.axiomancer.io) and [report](https://locus.axiomancer.io/report) page now meet WCAG AA contrast standards across hero copy, sub-text, and the cross-product bar's inactive product labels. Both pages also expose a proper `

` landmark so screen readers can jump straight to the primary content. No action is required on your part. ## Improved accessibility on the Overwatch homepage [#improved-accessibility-on-the-overwatch-homepage] The [Overwatch homepage](https://axiomoverwatch.io) now meets WCAG AA contrast standards in the footer — de-emphasized footer copy that previously failed contrast checks is now legible against the dark background, while keeping the same visual hierarchy. The page also exposes a proper `

` landmark so screen readers can jump straight to the primary content, and footer column headers use a correct heading order so audits like Lighthouse no longer flag the home page. No action is required on your part. ## Higher-contrast labels on the live system-status chip [#higher-contrast-labels-on-the-live-system-status-chip] The floating system-status chip on the [Overwatch homepage](https://axiomoverwatch.io) — which surfaces live AIS position and vessel counts — now renders its **POS** and **VESSELS** caption labels at WCAG AA contrast against the chip's amber-tinted background. Footer de-emphasis tiers were also retuned in the same pass so that secondary and tertiary footer copy both clear the AA threshold against the dark page background. No action is required on your part. ## Sharper page titles and accurate signal counts [#sharper-page-titles-and-accurate-signal-counts] The Locus homepage and the [report](https://locus.axiomancer.io/report) page now have their own titles, descriptions, and link previews instead of falling back to a generic site-wide default. Sharing either URL on Slack, LinkedIn, or X will show preview cards tailored to the page. The [signals](https://locus.axiomancer.io/signals) page also now reads its signal-group and data-source counts directly from the live catalog, so the description stays accurate as new sources come online. ## Final contrast tweaks for de-emphasized text and the Locus accent [#final-contrast-tweaks-for-de-emphasized-text-and-the-locus-accent] Two remaining contrast misses on [locus.axiomancer.io](https://locus.axiomancer.io) are now fixed. De-emphasized copy in the Locus page ticker now renders at WCAG AA contrast on the lighter surface where it lives, and the Locus accent in the cross-product bar at the top of every Axiom site has been lifted on its dark background so it also clears AA. The canonical Locus brand color is unchanged everywhere else. No action is required on your part. ## In-app support chat and link previews load reliably across browsers [#in-app-support-chat-and-link-previews-load-reliably-across-browsers] The Layer dashboard's Content Security Policy now allows the full set of providers it actually depends on — including Intercom for in-app support chat, Mux for embedded video, and the analytics stack used to power [scheduled reports](/layer/billing) and usage dashboards. Previously, browsers enforcing strict CSP would silently block these requests, which could cause the support widget to fail to load and tracked events to be dropped. Existing sessions are unaffected; the fix takes effect on the next page load. No action is required on your part. ## Mux storyboard thumbnails load on the Layer marketing site [#mux-storyboard-thumbnails-load-on-the-layer-marketing-site] The hero video on [axiomlayer.io](https://axiomlayer.io) now displays scrub-bar storyboard thumbnails correctly across browsers enforcing strict CSP. Mux Player loads its preview images from `image.mux.com`, which was missing from the marketing site's `media-src` allowlist and was being silently blocked. The host has been added so storyboard previews render as expected. The hero video itself was unaffected. No action is required on your part. ## Mux storyboard thumbnails load on the Codex marketing site [#mux-storyboard-thumbnails-load-on-the-codex-marketing-site] The hero video on [axiomcodex.io](https://axiomcodex.io) now displays scrub-bar storyboard thumbnails correctly across browsers enforcing strict CSP. Mux Player loads its preview images from `image.mux.com`, which was missing from the marketing site's `media-src` allowlist and was being silently blocked by browsers — a violation that was also surfacing in Lighthouse best-practices audits. The host has been added so hover-scrub previews render as expected. The hero video itself was unaffected. No action is required on your part. ## Cleaner browser console on the Codex marketing site [#cleaner-browser-console-on-the-codex-marketing-site] Every page on [axiomcodex.io](https://axiomcodex.io) now loads its favicon and tab icons cleanly, eliminating a 404 that was firing on every navigation and surfacing as a console error. The site now points at the existing Codex brand mark, so browser tabs, bookmarks, and pinned tab previews show the proper icon. No action is required on your part. ## Higher-contrast subtle text and category pills on the Layer marketing site [#higher-contrast-subtle-text-and-category-pills-on-the-layer-marketing-site] A follow-up Lighthouse audit caught two remaining contrast misses on [axiomlayer.io](https://axiomlayer.io). De-emphasized "subtle" copy on dark marketing surfaces — used for captions, eyebrow labels, and supporting microcopy — now renders at WCAG AA contrast against the dark background. The inactive category pills on the integrations wall (used to filter by IDP, MDM, finance, and so on) have also been darkened so their labels clear AA contrast on the light pill background. The canonical brand palette is unchanged everywhere else. No action is required on your part. ## Footer copy now meets WCAG AA contrast on the Overwatch homepage [#footer-copy-now-meets-wcag-aa-contrast-on-the-overwatch-homepage] A follow-up audit caught two tiers of de-emphasized footer text on the [Overwatch homepage](https://axiomoverwatch.io) that were still falling below the WCAG AA threshold against the dark background. Both tiers have been lifted so they now clear AA contrast for normal-weight text, while preserving the existing visual hierarchy between primary, secondary, and tertiary footer copy. No action is required on your part. ## Higher-contrast labels on the live system-status chip [#higher-contrast-labels-on-the-live-system-status-chip-1] The "POS" and "VESSELS" labels on the floating system-status chip shown on the [Overwatch homepage](https://axiomoverwatch.io) now use a lighter slate tone that meets WCAG AA contrast against the chip's tinted background. The status values themselves and the chip's overall styling are unchanged. No action is required on your part. ## H3 spatial index populated on AISHub vessel positions [#h3-spatial-index-populated-on-aishub-vessel-positions] AIS positions ingested from the AISHub REST source were being written without an `h3_index` value, leaving spatial joins between [`ais_positions`](/codex/schemas/ais-maritime) and other H3-indexed datasets incomplete for that subset of rows. Each AISHub position now computes the resolution-8 H3 cell at write time, matching the [Codex normalization standard](/codex/normalization-standard) already enforced for AISStream and other Overwatch ingestion paths. This brings `h3_index_pct` for `ais_positions` back to 100% on the [envelope coverage dashboard](/codex/envelope-coverage), so queries that join on `h3_index` — including terminal-level port call attribution — return the full set of AIS-derived results again. No action is required on your part. ## Live vessel positions endpoint restored [#live-vessel-positions-endpoint-restored] Fixed an issue where the live-vessels endpoint that powers the [Overwatch](/overwatch) map was returning a 500 error after a recent change to the underlying [AIS retention](/overwatch/data-retention) layout. The endpoint now resolves the per-vessel last-seen timestamp correctly, so live map views and any external integrations consuming the same GeoJSON feed start populating again. The public response shape is unchanged. No action is required on your part. ## Cleaner browser console for anonymous visitors [#cleaner-browser-console-for-anonymous-visitors] Anonymous visitors to [axiomoverwatch.io](https://axiomoverwatch.io) no longer see a spurious 401 in the browser console from the in-app support messenger's identity check. The messenger now correctly treats unauthenticated visitors as anonymous without surfacing the warning. Behavior for signed-in users is unchanged. No action is required on your part. ## Improved accessibility on the Overwatch blog [#improved-accessibility-on-the-overwatch-blog] The [Overwatch blog](https://axiomoverwatch.io/blog) index and individual blog posts now expose a proper `

` landmark, so screen readers can jump straight to post content. De-emphasized slate copy on both pages was also lifted past WCAG AA contrast against the dark background, matching the contrast tier already used on the Overwatch homepage footer. The visual hierarchy is unchanged. No action is required on your part. ## Docs link on the Axiomancer Labs landing page [#docs-link-on-the-axiomancer-labs-landing-page] The [Axiomancer Labs landing page](https://axiomancer.io) now exposes a **Docs** link in both the top navigation and the footer, so you can jump to the docs from the parent site without first navigating into a specific product. The link lands on the docs root, where the cross-product bar takes over to route you to Layer, Overwatch, Locus, or Codex docs. No action is required on your part. ## Higher-contrast solid buttons on the Axiomancer Labs landing page [#higher-contrast-solid-buttons-on-the-axiomancer-labs-landing-page] Solid-fill buttons on the [Axiomancer Labs landing page](https://axiomancer.io) — including primary CTAs that use the cyan brand fill — now render with dark label text instead of white, lifting them well past WCAG AA contrast for normal-weight text. The CTA glow was also retuned from a stale purple to a cyan tone so the shadow matches the button fill. The canonical brand palette is unchanged everywhere else. No action is required on your part. ## Axiomancer Labs landing page brand colors aligned [#axiomancer-labs-landing-page-brand-colors-aligned] The cross-product bar on the [Axiomancer Labs landing page](https://axiomancer.io) now uses the updated pink accent for Layer and indigo accent for Locus, matching the refreshed brand identity used everywhere else on the platform. Inactive product labels in the bar were also lifted to meet WCAG AA contrast against the dark background. No action is required on your part. ## Higher-contrast shared footer across Locus content pages [#higher-contrast-shared-footer-across-locus-content-pages] The shared content footer on [locus.axiomancer.io](https://locus.axiomancer.io) — used across the [pricing](https://locus.axiomancer.io/pricing), [blog](https://locus.axiomancer.io/blog), [pulse](https://locus.axiomancer.io/pulse), and [docs](https://locus.axiomancer.io/docs) pages — now meets WCAG AA contrast standards. Column headings, body copy, the copyright line, and the **Privacy** and **Terms** links were running at low alpha values that fell short of the contrast threshold against the dark background. All four tiers were lifted in a single sweep, matching the contrast already used on the home and report pages. The visual hierarchy is unchanged. No action is required on your part. ## Improved accessibility on the Overwatch platform page [#improved-accessibility-on-the-overwatch-platform-page] The [Overwatch platform page](https://axiomoverwatch.io/platform) now exposes a proper `

` landmark so screen readers can jump straight to the primary content. Section headings under **Live products**, **Coming Q3**, and **Who uses Overwatch** were promoted to a correct level so the page reads as a clean outline in audits like Lighthouse. De-emphasized slate copy across the page was also lifted past WCAG AA contrast against the dark background, matching the contrast tier already used on the Overwatch homepage and blog. The visual hierarchy is unchanged. No action is required on your part. ## Larger tap targets on the Overwatch blog sidebar [#larger-tap-targets-on-the-overwatch-blog-sidebar] Sidebar links on the [Overwatch blog](https://axiomoverwatch.io/blog) now clear the 24×24 pixel minimum tap-target size recommended by Lighthouse and WCAG. Each link in the **Links** column was previously rendered as bare text with tight row spacing, which left only a \~20 pixel safe-click diameter and could be hard to hit accurately on touch devices. The links now sit on padded rows with a slightly larger gap between them, so every entry exposes a comfortable tap target. The visual hierarchy and link styling are unchanged. No action is required on your part. ## Improved accessibility on Layer login and signup pages [#improved-accessibility-on-layer-login-and-signup-pages] The Layer [login](https://axiomlayer.io) and signup pages now expose a proper `

` landmark, so screen readers can jump straight to the form without scanning past the page chrome. The primary **Sign in** and **Create account** buttons, along with the inline link between the two pages, now use a stronger indigo that clears WCAG AA contrast for white text. The visual hierarchy and brand palette are unchanged everywhere else. No action is required on your part. # April 26, 2026 (/changelog/2026-04-26) ## Service status page [#service-status-page] Overwatch now includes a built-in [status page](/overwatch/status-page) that shows real-time health for core platform services — database connectivity, AIS data freshness, ingestion pipeline, and visit pipeline. Each service displays its current state (operational, degraded, or down) along with a 24-hour visual timeline so you can spot intermittent issues at a glance. Health checks run every 5 minutes, and three consecutive failures trigger an automatic alert. A programmatic health endpoint is also available for external monitoring tools. Visit the status page from **Dashboard > Status**. ## Backfilled cargo estimates for historical vessel visits [#backfilled-cargo-estimates-for-historical-vessel-visits] Approximately 16,000 past vessel visits that were missing hydrostatic cargo estimates have now been retroactively processed. If you previously saw gaps in [cargo data](/overwatch/methodology/cargo-validation) for departed vessels, those visits now include tonnage estimates calculated using the same methodology as live arrivals. No action is required on your part. ## Cross-product navigation bar now visible on all pages [#cross-product-navigation-bar-now-visible-on-all-pages] The Axiom navigation bar was missing from several pages including intelligence, blog, pricing, and dashboard sub-pages. It now appears consistently across every Overwatch page, so you can switch between Layer, Overwatch, Locus, and Codex from anywhere in the application. ## Fixed crash on first page load [#fixed-crash-on-first-page-load] Resolved an issue where the Locus application could display a generic "Application error" screen on first visit. The crash was caused by analytics initialization running in the wrong order during page load. The fix ensures analytics are fully initialized before any page tracking occurs, so the app loads reliably on first visit. No action is required on your part. ## Branded social preview cards for Layer [#branded-social-preview-cards-for-layer] Links to [axiomlayer.io](https://axiomlayer.io) now render a branded preview card when shared on Slack, Twitter, LinkedIn, and other platforms that read OpenGraph metadata. The 1200×630 image uses the Layer pink and indigo brand palette and highlights the free shadow IT scan. No action is required on your part — existing links will pick up the new preview the next time the destination platform refreshes its cache. # April 27, 2026 (/changelog/2026-04-27) ## Safety tier distribution on the Explorer rail [#safety-tier-distribution-on-the-explorer-rail] The Intelligence Rail on the [Locus explorer](/locus/explorer#safety-tier-distribution) now includes a stacked-bar visualization showing how the focused metro's scored cells distribute across five safety tiers — **Prime** (≥80), **Strong** (60–79), **Solid** (40–59), **Watch** (20–39), and **Elevated** (\<20). The mix tells you at a glance whether a metro is mostly safe or mostly elevated without having to scrub the map. The bar is backed by a new generic endpoint, [`GET /api/metro-tier-distribution`](/locus/api/discovery-and-intelligence#get-apimetro-tier-distribution), which buckets any of the eight signal-group columns (or `composite`) by tier for a given metro. The same component will power distribution bars for development pipeline, business vitality, and other groups in future panels — pass a different `signal` query parameter to compute a different mix without a new route. No action is required on your part. ## Bloomberg-style terminal at /dashboard [#bloomberg-style-terminal-at-dashboard] The Overwatch dashboard at [`/dashboard`](/overwatch/getting-started) has been rebuilt as a fixed-viewport, terminal-style HUD with two preset modes — **TRADE** for commodity flow tracking and **SANC** for sanctions analytics — each laying out 12 live-data panels (port-flow heatmap, live vessel mini-map, export forecasts, berth utilization, commodity tape, trade-flow tracker, active alerts, dark-fleet map, anomaly queue, risk profiles, verification queue, and a recent-events stream). The terminal supports keyboard navigation: `F1`–`F12` jump straight to the equivalent dashboard sub-route, and `⌘K` (or `Ctrl+K`) opens a command palette to search panels and tools. Pin actions on the panels are backed by your existing watchlist, so vessels you've pinned stay surfaced across panels. A simplified mobile view is shown on small screens. The previous landing page is preserved at [`/dashboard/overview`](/overwatch/getting-started) and reachable via `F12` or the command palette. All 24 dashboard sub-routes still work as before. ## Public global vessel positions endpoint [#public-global-vessel-positions-endpoint] A new public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint returns a global GeoJSON `FeatureCollection` of the latest known position for every tracked vessel (\~18K) in a single request. No auth required, CDN-cached for five minutes, and supports an optional `type` filter and bounding box (`west`, `south`, `east`, `north`) for regional snapshots — antimeridian-crossing boxes included. The full global payload is \~800 KB gzipped. Use it to power your own live map, heatmap, or periodic dashboard refresh instead of paging port-by-port. ## Instant panning on the Overwatch live map [#instant-panning-on-the-overwatch-live-map] Panning the [live map](/overwatch/getting-started) to a new region of the globe is now instant — no more empty-map flash while a region-specific request comes back. The map now loads the full global vessel layer once on first paint and renders every subsequent pan and zoom from data already on the client, matching the always-on-globe feel of VesselFinder and MarineTraffic. Positions still refresh automatically every five minutes, so the layer stays current without any extra requests. No action is required on your part. ## Faster hero video startup on the Overwatch homepage [#faster-hero-video-startup-on-the-overwatch-homepage] The hero video on [axiomoverwatch.io](https://axiomoverwatch.io) now starts playing noticeably faster on first visit. The browser opens a TLS connection to the Mux video origins while the rest of the page is still parsing, so the handshake is already warm by the time the player is ready to stream. No action is required on your part. ## Sharper homepage paint on Overwatch [#sharper-homepage-paint-on-overwatch] Followed up on the hero video startup work with an additional paint improvement on [axiomoverwatch.io](https://axiomoverwatch.io). The hero thumbnail — the largest visible element on first load — is now declared as a preload hint in the initial document, so the browser fetches it in parallel with the rest of the page rather than waiting until the video player mounts. The same prefetched image is reused as the player's poster, so there's only one network request for it. The result is a noticeably earlier first paint of the homepage hero on cold visits. No action is required on your part. ## Equasis enrichment failures down from 98.8% to baseline [#equasis-enrichment-failures-down-from-988-to-baseline] Fixed an issue where the first vessel in every [Equasis enrichment](/overwatch/api/vessels) batch was failing immediately after a fresh login, then triggering an unnecessary re-authentication that often failed too. An audit found this pattern accounted for 98.8% of recent enrichment-queue failures (5,503 of 5,570). The re-login path was already pre-warming the session before fetching vessel data, but the initial-login path skipped that step and went straight to the vessel-detail request — which Equasis rejects roughly 95% of the time on a brand-new session. Fresh logins now follow the same warmup flow as re-logins, so registered owner, flag state, and deadweight tonnage populate on the first attempt instead of the third. Underlying HTTP status and reason are now also propagated into enrichment error messages so future failures can be diagnosed without re-running the batch. No action is required on your part. ## More resilient ingestion of cultural amenity data [#more-resilient-ingestion-of-cultural-amenity-data] Cultural amenity records ingested from OpenStreetMap could fail to load when an upstream `start_date` tag used a freeform value like `"1870"` or `"c. 1900"` that isn't a valid timestamp. The ingestion job now validates the date before using it and falls back to the ingestion time when the value can't be parsed, so the long tail of historical sites flows in cleanly alongside the rest. Coverage on the [envelope dashboard](/codex/envelope-coverage) for `osm_cultural_amenities` is unchanged. No action is required on your part. ## More reliable vessel enrichment on first login [#more-reliable-vessel-enrichment-on-first-login] [Vessel metadata enrichment](/overwatch/api/vessels) from Equasis was failing on the first vessel of nearly every batch because the initial-login path skipped the session warm-up step that the re-login path already performed. The first request to the upstream service was bouncing roughly 95% of the time, which then triggered an unnecessary re-login per batch. The fresh-login path now warms the session before the first request, so registered owner, flag state, and deadweight tonnage populate consistently from the start of every run. No action is required on your part. ## Safety score no longer reads "100" from flood zone alone [#safety-score-no-longer-reads-100-from-flood-zone-alone] The **Safety & Environment** sub-score on Locus cells now requires at least two contributing sub-signals to produce a measured score. Previously, cells with no crime, EJScreen, NRI, air-quality, or 311 data — which is most cells outside the largest US metros — were scoring 100/100 on safety purely because FEMA flood zone is universally available and most US locations sit in the low-risk `X` zone (which maps to a sub-score of 100). With only one input feeding the group's weighted average, lack of crime data was being silently read as "fully safe." Affected cells now return `safetyEnvironment.score: 50` with `confidence: 0` and an empty `subScores` array, signaling **no safety signal available** rather than masking sparse coverage as a perfect score. Use the `confidence` field to filter these cells out of safety-sensitive ranking lists. See [coverage guards on signal groups](/locus/scoring-conventions#coverage-guards-on-signal-groups) for the full rule. ## More accurate neighborhood names on Locus cells [#more-accurate-neighborhood-names-on-locus-cells] Locus now resolves neighborhoods to the names you'd recognize from Google Maps — places like *SoHo*, *Williamsburg*, or *Mission District* — instead of the administrative subdivisions that the previous source returned (NYC Community Boards like *Manhattan Community Board 2*, or generic township and city names in other metros). Cell [enrichment](/locus/api/enrichment), [scoring](/locus/scoring-conventions), and [location lookups](/locus/api/location-data) now prefer curated polygons that match the everyday neighborhood you'd expect, with OpenStreetMap and Census fallbacks for areas without curated coverage. Existing rows that returned a Community District name have already been cleared, and a backfill is in progress to populate full neighborhood coverage across all 22 supported metros. No action is required on your part. ## Live map controls no longer clip on shorter viewports [#live-map-controls-no-longer-clip-on-shorter-viewports] Resolved an issue on the [Overwatch live map](/overwatch/getting-started) where the trail playback controls could be cut off at the bottom of the viewport and the viewport-loading disclaimer overlapped the vessel-types legend. The trail controls now respect the browser's safe-area inset, the vessel-types legend reflows above the trail controls on shorter screens, and the disclaimer is hidden on desktop where the legend already conveys the same information. No action is required on your part. ## Live map trail controls now fully visible on mobile browsers [#live-map-trail-controls-now-fully-visible-on-mobile-browsers] Followed up on the earlier safe-area fix for the [Overwatch live map](/overwatch/getting-started). On mobile browsers, the trail-playback button could still appear half-hidden behind the dynamic URL bar because the map sized itself to the full viewport (`100vh`) rather than the visible viewport. The map now sizes to the dynamic viewport (`100dvh`), and the trail controls and vessel-types legend are pinned a fixed offset above the safe-area inset, so both controls stay fully on-screen as the URL bar shows and hides while you scroll. No action is required on your part. ## NYC neighborhood coverage restored after upstream dataset withdrawal [#nyc-neighborhood-coverage-restored-after-upstream-dataset-withdrawal] The NYC Open Data feed that supplies New York City neighborhood polygons for [enrichment](/locus/api/enrichment), [scoring](/locus/scoring-conventions), and [location lookups](/locus/api/location-data) was withdrawn upstream, which left some NYC cells without a friendly neighborhood name. Locus has switched to the current 2020 Neighborhood Tabulation Areas dataset, so names like *East Village*, *Lower East Side*, and *Murray Hill-Kips Bay* now resolve correctly again instead of falling back to *Manhattan Community Board 3* or similar administrative subdivisions. The OpenStreetMap fallback that covers metros outside NYC was also failing on requests that didn't identify themselves to the Overpass API — those requests now succeed, so curated polygons load reliably across all 22 supported metros. Existing affected rows have been cleared and the backfill is repopulating coverage automatically. No action is required on your part. ## Neighborhood polygons now support islands and exclaves [#neighborhood-polygons-now-support-islands-and-exclaves] Neighborhood boundaries in Locus can now contain multiple disjoint polygons — useful for areas that span an island, an exclave, or a peninsula separated by water. Previously, multi-part shapes were silently truncated to their largest piece, so a [neighborhood lookup](/locus/api/location-data) inside a smaller component could miss the match and fall back to a coarser administrative name. All curated and OSM-sourced polygons now preserve their full geometry, which keeps neighborhood resolution consistent with what you'd see on Google Maps. No action is required on your part. ## Faster home page on locus.axiomancer.io [#faster-home-page-on-locusaxiomancerio] The hero video poster on [locus.axiomancer.io](https://locus.axiomancer.io) — the Largest Contentful Paint element on the home page — now loads noticeably sooner on first visit. The browser is told to preload the poster image at high priority directly from the initial document, instead of waiting for the player to mount, so the hero appears earlier in the page lifecycle. The poster is also requested from a CDN-warm preset size, dropping roughly 1.3 MB from the home page payload at the same visual quality and avoiding the multi-second origin-resize stall that was hitting first-time visitors. No action is required on your part. ## Hardened budget caps on POI ingestion [#hardened-budget-caps-on-poi-ingestion] The pipelines that refresh [POI inventory](/locus/scoring-conventions#data-freshness) for Locus scoring now run with a small safety margin under each upstream provider's free-tier ceiling, instead of stopping exactly at it. Per-key Google Places usage now caps at 6,200 calls per billing period (down from 6,250) and the global weekly collection budget caps at 43,000 calls (down from 43,750), so concurrent jobs racing on the same counter can no longer push usage one call past the free credit. Yelp also now has an explicit monthly cap of 4,800 calls under its 5,000-call free tier, where previously only the response cache prevented overspend. POI freshness on the [data freshness table](/locus/scoring-conventions#data-freshness) is unchanged — the weekly refresh still completes well within the new budgets. No action is required on your part. ## Composite-driven ranking lists now preview top 3, unlock on Analyst+ [#composite-driven-ranking-lists-now-preview-top-3-unlock-on-analyst] The eight composite-driven [ranking lists](/locus/mcp-server) on Locus — *Top Overall*, *Fastest Growing (Axiom Composite)*, *Safest Urban*, *Most Business-Active*, *Best for Restaurants*, *Strongest Economies*, *Best Accessibility*, and *Development Hotspots* — now show the top 3 rows to free and signed-out visitors and unlock the full top 25 on the **Analyst** plan ($49/mo) or any higher tier (Pro, Team, Enterprise, Supply Chain Risk). The paywall is enforced server-side in `getRankingResults()` at the data layer, not in the rendered HTML — locked rows never reach the page source, so they cannot be inspected, scraped, or unlocked client-side. The same gating applies whether you reach a list through the web UI, the [`axiom_get_rankings` MCP tool](/locus/mcp-server#available-tools), or the underlying API. The `/rankings` index page now groups tiles into two sections — **Public Data — Free** and **Axiom Composite — Analyst+** — and locked tiles wear an *Analyst+* badge with a *Preview (top 3)* CTA instead of *View ranking*. Per-list pages render an unlock card after the preview rows when results are truncated, with the Analyst tier price stated inline. Public rankings sourced from verifiable third-party data — [Fastest-Growing by Population](#public-fastest-growing-by-population-ranking) (U.S. Census ACS), [Most Building Permits](#public-most-building-permits-ranking) (municipal permit databases), and FHFA-derived lists — are unaffected and continue to render in full to all visitors. No action is required if you're already on a paid plan. ## Source attribution on every Locus ranking list [#source-attribution-on-every-locus-ranking-list] Every curated [ranking list](/locus/mcp-server) on Locus now renders a citation footer below the table, naming the data source the list is derived from and linking to the underlying methodology. Each ranking definition declares its own `dataSource` and `citationUrl`, so future lists built on third-party datasets — Census migration flows, BLS employment, FBI safety data — will surface the original source under the table instead of being indistinguishable from composite-driven lists. The current eight composite lists (*Top Overall*, *Fastest Growing*, *Safest*, *Most Business Active*, *Best for Restaurants*, *Strongest Economies*, *Best Accessibility*, *Development Hotspots*) all cite the [Axiom Composite Score methodology](https://axiomlocus.io/methodology). No action is required on your part. ## Public Most Building Permits ranking [#public-most-building-permits-ranking] Locus now publishes a free, fully-unlocked **Most Building Permits Issued (Last 12 Months)** ranking that surfaces where construction is most active right now. The list is sourced directly from municipal building-permit open data — 1.2M permits indexed across 10 metros — and cross-referenced with the [U.S. Census Building Permits Survey](https://www.census.gov/construction/bps/), so every number is independently verifiable in your city's open-data portal. Like other public lists, the ranking renders in full with no preview cap and exposes columns tailored to its purpose instead of Axiom sub-scores: total permits issued in the trailing 12 months, total declared valuation, and the count of distinct permit types. The materialized cell index refreshes nightly, so freshly issued permits flow through to the leaderboard within a day. No action is required on your part. ## Public Fastest-Growing by Population ranking [#public-fastest-growing-by-population-ranking] Locus now publishes a free, fully-unlocked **Fastest-Growing Neighborhoods (Population)** ranking sourced directly from U.S. Census ACS 5-year estimates, alongside the existing composite list (now disambiguated as **Fastest-Growing Neighborhoods (Axiom Composite)**). The new list ranks neighborhoods on raw population change between two consecutive ACS vintages — the universally-understood definition of "fastest growing" — and is cited back to [census.gov/programs-surveys/acs](https://www.census.gov/programs-surveys/acs/) so results are independently verifiable. Unlike composite-tier rankings, public lists render in full (no preview cap) and expose population-specific columns instead of Axiom sub-scores: percent change year-over-year, current and prior population counts, and the ACS vintage used. The composite **Fastest-Growing** list is unchanged — it continues to rank on Axiom's `population_momentum` signal, which captures leading indicators that anticipate raw population change. Use the public list when you need a defensible, third-party-cited answer; use the composite list when you want Axiom's forward-looking signal. The ranking populates per metro as the second ACS vintage backfill completes. No action is required on your part. ## Public Most Building Permits ranking [#public-most-building-permits-ranking-1] Locus now publishes a second free, fully-unlocked public ranking — **Most Building Permits Issued (Last 12 Months)** — that surfaces where construction is most active right now. The list is sourced directly from municipal building-permit databases (1.2M permits across 10 metros at launch, with Boston downtown leading at 1,469 permits in the trailing 12 months) and cross-referenced against the U.S. Census Building Permits Survey at [census.gov/construction/bps](https://www.census.gov/construction/bps/), so every number is independently verifiable in the underlying city open-data portal. Like the [Fastest-Growing by Population](#public-fastest-growing-by-population-ranking) list, this ranking renders in full with no preview cap and exposes permit-specific columns instead of Axiom sub-scores: total permits issued in the last 12 months, total permit valuation in dollars, and the count of distinct permit types observed in the cell. Underlying data is pre-aggregated into a materialized view across H3 cells and refreshed nightly, so the list reflects yesterday's filings. The list ranks on absolute permit count rather than per-capita — a per-capita variant is planned and will roll in once the second ACS vintage backfill completes. Use this list when you need a forward-looking, defensible signal of where development is happening; pair it with the composite [Development Hotspots](/locus/mcp-server) list when you want Axiom's blended signal that combines permits with construction intensity and land-use change. No action is required on your part. ## Ranking pages now show the columns each list is sorted by [#ranking-pages-now-show-the-columns-each-list-is-sorted-by] Each curated [ranking list](/locus/mcp-server) on Locus — *Top Overall*, *Fastest Growing*, *Safest*, *Most Business Active*, *Best for Restaurants*, *Strongest Economies*, *Best Accessibility*, and *Development Hotspots* — now renders the columns that actually drive its sort, with the primary metric featured in big-number style next to a sort-direction indicator. Previously every list showed the same five score columns regardless of which list you were viewing, which buried safety on the *Safest* list and demographics on *Best for Restaurants*. Mobile cards mirror the same column order, so the headline metric matches the list's purpose on both layouts. No action is required on your part. ## National activity heatmap on the Locus explorer [#national-activity-heatmap-on-the-locus-explorer] The map on [locus.axiomancer.io/explore](https://locus.axiomancer.io/explore) now shows a single national heatmap of activity across the country, instead of a metro-scoped overlay that saturated to a solid red square inside whichever metro you were viewing. The new layer aggregates the last 90 days of geocoded events into hexagonal cells nationwide, weights them by event count, and retunes the color stops so dense metros like New York and Los Angeles read as the hottest spots without blowing out everywhere else. The legend now resolves at country-wide zoom, so you can compare relative activity between metros at a glance. The explorer sidebar also picked up an explicit **Back to Dashboard** link and a brand link, so you can return to the rest of Locus without using the browser back button. ## Sign-in and explorer back-link now land on the Locus dashboard [#sign-in-and-explorer-back-link-now-land-on-the-locus-dashboard] Signing in to Locus now drops you on the authenticated dashboard at `/dashboard` instead of the [explorer](https://locus.axiomancer.io/explore) map, and the explorer sidebar's **Back to Dashboard** link points to the same place instead of the marketing landing page at `/`. Previously, the OAuth callback at `/auth/callback` defaulted post-login traffic straight to the map, so first-time and returning users alike skipped past the dashboard summary, ranking lists, and recent activity that the dashboard surfaces. The back-link from the explorer was likewise sending signed-in users out of the app and onto the public landing page. Both flows now route through the dashboard, which is the actual home for authenticated Locus sessions. No action is required on your part. ## Integration OAuth connections save reliably on first connect [#integration-oauth-connections-save-reliably-on-first-connect] Connecting a new [integration](/layer/integrations/overview) — Google Workspace, Microsoft 365, Okta, Slack, GitHub, or any other connector that uses OAuth — now saves the connection on the first attempt instead of redirecting back to the integrations page with a `save_failed` banner. The OAuth callback was running the database insert under the user's session, which on freshly-provisioned workspaces didn't yet carry the workspace claim that row-level security policies require. The callback now writes through a workspace-scoped server path that already has authoritative tenant context from the [workspace auto-provision flow](/layer/getting-started), so the insert succeeds whether the workspace was created seconds earlier or months ago. Connections that previously failed can be retried from the [Integrations page](https://app.axiomlayer.io/integrations) without any other action. ## Integration save failures now show the underlying reason [#integration-save-failures-now-show-the-underlying-reason] When saving an [integration connection](/layer/integrations/overview) fails for any reason, the integrations-page banner now surfaces the underlying error message via a `?detail=…` query parameter on the redirect — matching the same pattern used for [sign-up errors](/layer/getting-started). Previously, all save failures collapsed to a generic "save\_failed" banner that required digging into server logs to diagnose. Self-hosted and preview deployments benefit the most: a misconfigured credential, missing scope, or upstream API error now produces an actionable message on screen so you can tell at a glance whether to retry, fix configuration, or contact support. No action is required on production tenants. ## Connector logos now render across the integrations catalog [#connector-logos-now-render-across-the-integrations-catalog] Logos for Microsoft 365, AWS, Jamf, JumpCloud, and other trademark-protected vendors now display correctly throughout the [integrations catalog](/layer/integrations/overview) and connect modal. The previous CDN refused to serve trademarked marks and 404'd on roughly a third of the catalog, leaving a colored-letter placeholder where the brand logo should have been. The catalog now sources logos from a CDN with comprehensive vendor coverage, with the colored-letter placeholder still in place for connectors that genuinely have no published mark. No action is required on your part. ## Workspaces auto-provision on first dashboard load [#workspaces-auto-provision-on-first-dashboard-load] New users who reached Layer through paths that bypassed the standard sign-in callback — for example, clicking straight into the dashboard, completing an [integration](/layer/integrations/overview) OAuth handshake, or kicking off the free [shadow IT scan](/layer/integrations/google-workspace) — could hit a dead-end "Unauthorized" or `no_tenant` error if their workspace hadn't been created yet. Layer now creates the workspace on the fly the first time you land on the dashboard, the integration connect callback, or the shadow-scan submission, so first-touch flows complete without an error screen. Existing users are unaffected. No action is required on your part. ## Email/password sign-up with a workspace name now succeeds [#emailpassword-sign-up-with-a-workspace-name-now-succeeds] A regression in workspace provisioning was silently rolling back email/password sign-ups whenever the form included an `organization_name`: the underlying database trigger wrote the new workspace membership to the wrong column, the transaction aborted, and the user account was never persisted. Affected sign-ups appeared to "succeed" in the browser but no account was created and no confirmation email arrived. The trigger has been corrected and applied as an idempotent migration, so [getting started](/layer/getting-started) now works end-to-end whether you sign up with Google, Microsoft, or email and password. If you tried to sign up earlier and never received a confirmation email, retry from [app.axiomlayer.io](https://app.axiomlayer.io) — your previous attempt left no record behind. ## Safety scores no longer rely on flood zone alone [#safety-scores-no-longer-rely-on-flood-zone-alone] Locus [safety scores](/locus/scoring-conventions) for cells with only a FEMA flood zone available — and no crime, environmental justice, NRI, air quality, or 311 data — were reading as 100/100 purely because most U.S. cells fall in flood zone X. With only one sub-signal present, the weighted average let that single source dominate and silently turned absent crime data into a "fully safe" score. The safety group now requires at least two sub-signals to be present before producing a number; cells with fewer fall through to the standard no-signal value of 50 instead. Cells with full safety coverage are unaffected. No action is required on your part. ## Sign-up errors now show why workspace setup failed [#sign-up-errors-now-show-why-workspace-setup-failed] When workspace provisioning during sign-up fails — for example, because a server-side credential is misconfigured — the login page now shows the underlying reason inline instead of just a generic "couldn't finish setting up your organization" message. The on-the-fly provisioner used by the dashboard, the [OAuth callback](/layer/getting-started), and the [free shadow IT scan](/layer/integrations/google-workspace) all surface the same detail through a `?detail=…` query parameter on the redirect, so you can tell at a glance whether to retry, contact support, or check your own configuration. Self-hosted and preview deployments benefit the most: an unset service-role key or a database-level error now produces an actionable message on screen instead of a silent dead-end. No action is required on production tenants. ## Free location reports now require CAPTCHA and email confirmation [#free-location-reports-now-require-captcha-and-email-confirmation] The free Location Report request flow on [locus.axiomancer.io](https://locus.axiomancer.io) now ships with two layers of abuse protection so it can't be used to mail unsolicited reports to non-consenting recipients. The form renders a Cloudflare Turnstile CAPTCHA, and the submit step no longer mails a report directly — it queues the request and sends the recipient a confirmation link with a 24-hour expiry. The full PDF is generated and delivered only after the recipient clicks through to confirm. A new **Report confirmed** landing page acknowledges the click with clear states for expired or invalid tokens and surface-level error reporting. Per-IP and per-recipient daily rate limits provide a further backstop. Legitimate workflows are unchanged aside from the one extra confirmation click on the recipient's side. No action is required on your part. # April 28, 2026 (/changelog/2026-04-28) This is a historical release record. Launch-supported chokepoint confirmation is currently AIS-only; Sentinel catalog coverage does not detect vessels or confirm transits. See the [current methodology](/overwatch/methodology/chokepoint-transits). ## Restored Seattle council decisions and zoning variance ingestion [#restored-seattle-council-decisions-and-zoning-variance-ingestion] Two upstream issues that were silently dropping civic data have been corrected. Seattle council decisions were being filtered out of the [Civic Intelligence](/codex/schemas/civic-intelligence) dataset because Seattle's Legistar template puts the bill *number* (for example, `CB 121195`) in the field most other cities use for the bill *title*. The development-keyword filter saw the file number, found no relevant terms, and discarded every Seattle matter. The Legistar HTML collector now prefers the canonical title and sponsoring-body fields and falls back to the legacy fields, so it works correctly across the San Francisco, New York City, Seattle, and Chicago templates simultaneously. Zoning variance records were also being lost. Every upsert raised a schema error because the writer was sending columns that don't exist on the `zoning_variances` table — introduction date, agenda date, file number, vote tallies, and action history — and the per-row error handling swallowed the failures, so the collector logged successful fetches with zero stored records. The writer now maps the relevant dates to the `filed_date` and `decision_date` columns and routes the remaining fields through the `source_record` JSON column, so no source data is lost. If you query Seattle council decisions or any city's zoning variances through the [Locus API](/locus/api/discovery-and-intelligence), the [MCP server](/locus/mcp-server), or the [Civic Intelligence schema](/codex/schemas/civic-intelligence), you should see records flowing again starting with the next collection run. No action is required on your part. ## Vessel density now renders as a shaded H3 hex map [#vessel-density-now-renders-as-a-shaded-h3-hex-map] The [`/dashboard/density`](/overwatch/getting-started) page on Overwatch now renders the daily vessel density layer as a viridis-shaded H3 hex map instead of a top-cells table. Each cell's polygon is colored by position count on a logarithmic scale, so dense traffic corridors and anchorage clusters read at a glance and tail-end activity stays visible alongside the hottest cells. Hover any cell to see its H3 index and exact `positions_count` and `unique_vessels`. The map is capped at 5,000 cells per render, fetches from the existing [`GET /api/v1/density`](/overwatch/api/density) endpoint, and respects the same vessel-type chip and day selector as before. The per-vessel-type rollup and freshness ledger indicator are unchanged. No action is required on your part. ## Locus admin routes now uniformly enforce the `ADMIN_EMAILS` allowlist [#locus-admin-routes-now-uniformly-enforce-the-admin_emails-allowlist] Every admin entrypoint on Locus — including the scoring-audit data fetcher at `/api/admin/scoring-audit` — is now gated by the same email allowlist used by the rest of `/admin/*`. The audit dashboard's data route was previously protected only by "must be signed in," meaning any authenticated free-tier user could read its payload; it now goes through the same `requireAdminApi()` check as every other admin API route, so requests from accounts not listed in `ADMIN_EMAILS` receive `403 Forbidden`. Self-hosted and preview deployments must set the `ADMIN_EMAILS` environment variable to a comma-separated list of admin email addresses (for example, `ADMIN_EMAILS=alice@example.com,bob@example.com`) — when the variable is unset, all admin pages and admin API routes fail closed for everyone, and the server logs a warning explaining how to populate it. Hosted Locus is unaffected. The variable is now also documented in the example env file shipped with the repo so fresh setups don't leave it blank by accident. No action is required if you already have `ADMIN_EMAILS` populated. ## Per-metro H3 resolution for low-density markets [#per-metro-h3-resolution-for-low-density-markets] Locus cell scoring now supports per-metro H3 resolution overrides. The default scoring resolution stays at **H3 r8** (\~0.74 km², \~490 m radius), which is right for dense urban grids — but in low-density, large-parcel metros an r8 cell often contains only a single CRE asset, leaving signal aggregation dominated by small-n noise. Ten metros are now scored at **H3 r7** (\~5.16 km², \~1280 m radius) instead so each cell carries enough samples to be statistically meaningful: **Phoenix, Houston, Las Vegas, Dallas, San Antonio, Nashville, Jacksonville, Oklahoma City, El Paso, and Fort Worth**. Every other metro continues to score at r8. Every row written to `cell_scores` is tagged with the resolution it was computed at via the existing `resolution_variant` column, so rankings, MAUP ensembles, and the explorer can distinguish r7 cells from r8 cells. If you query `cell_scores` directly across metros, filter or group on `resolution_variant` rather than assuming a single resolution. The override is additive — historical scores are unaffected and no action is required on your part. See [Per-metro resolution overrides](/locus/scoring-conventions#per-metro-resolution-overrides) for the full list and rationale. ## `general` scoring profile rebalanced against CRE price-correlation literature [#general-scoring-profile-rebalanced-against-cre-price-correlation-literature] The default `general` scoring profile on `/api/score` has been rebalanced to align signal weights with the empirical commercial real estate price-correlation research. Three signals carry the strongest published correlation and clearest lead times against CRE prices and have been bumped accordingly: **developmentPipeline** (building permits, R² ≈ 0.55 vs CRE prices, 6–12 month lead) moves from 0.12 to 0.20, **economicStrength** (employment density change via LEHD, 3–9 month lead) moves from 0.15 to 0.20, and **accessibility** (transit ridership, 12–24 month lead) moves from 0.10 to 0.12. The +0.15 weight increase is offset by trimming less-validated groups so the weights still sum to 1.0: **businessVitality** 0.20 → 0.15, **populationMomentum** 0.15 → 0.10, **demographics** 0.12 → 0.10, **amenityDemand** 0.08 → 0.05. **safetyEnvironment** keeps its 0.08 — crime remains the peer-reviewed safety predictor and OSHA/EPA aren't currently scoring inputs. The use-case profiles (`qsr`, `office`, `industrial`, `retail`, `data_center`, `self_storage`) are deliberately unchanged — they reflect industry-specific priorities rather than generic price prediction. If you call `/api/score` without a `profile` parameter (or with `profile=general`), expect composite scores to shift by a few points in either direction depending on the cell — cells strong on permits or employment density will trend up, cells primarily strong on demographics or amenities will trend down. Pin to the previous behavior with `profile_version` if you need replicable historical scores. See [scoring profiles](/locus/scoring-conventions#scoring-profiles) for the full weight table. ## Free location reports now require a captcha and email confirmation [#free-location-reports-now-require-a-captcha-and-email-confirmation] The [free location report](https://axiomlocus.io/free-report) form on Locus now runs requests through a Cloudflare Turnstile captcha and a double opt-in email confirmation before any report is sent. Previously, a single unauthenticated POST to `/api/free-report` would deliver an Axiom Locus *Location Report* to whichever recipient address the form named — with no captcha and no rate limit — which made the endpoint usable as a third-party email-bombing vector against non-consenting recipients on Axiom's sender reputation. The form now renders a Turnstile widget and submits the resulting token alongside the address and email; the server verifies the token before doing any paid work (geocoding, scoring, sending). After the captcha clears, the request is rate-limited to **5 submissions per day per IP** and **3 per day per recipient email**. The endpoint then geocodes the address, queues a row with a 32-byte single-use token and a 24-hour expiry, and emails *the recipient* a confirmation link. Only after the recipient clicks the link does Locus actually score the location and send the report — so a report can never reach an inbox that didn't explicitly opt in. The form redirects to a new **/report-confirmed** page with explicit success and error states (expired link, invalid or already-used token, scoring failure, send failure) so users can tell at a glance whether to retry. Re-clicking a confirmation link after it has been consumed is idempotent — the success page renders without re-scoring or re-sending. No action is required if you only consume Locus through the [authenticated API](/locus/api/overview); the consumer-facing free-report flow is the only surface affected. ## Safety tier mix on the Intelligence Rail [#safety-tier-mix-on-the-intelligence-rail] The [Locus explorer](https://locus.axiomancer.io/explore) Intelligence Rail now shows a **Safety Tier Mix** stacked-bar that breaks down how the active metro's scored cells distribute across five safety tiers — *Prime* (≥80), *Strong* (60–79), *Solid* (40–59), *Watch* (20–39), and *Elevated* (under 20). Each segment is sized by the share of cells in that tier, so a glance answers "is this metro mostly safe, or mostly elevated?" without leaving the rail. A small legend below the bar shows the exact percentage in each tier and the total cell count powering the chart. The same component is built to render distributions for any of the eight [signal groups](/locus/scoring-conventions) in future updates — development pipeline mix, business vitality mix, and so on. No action is required on your part. ## Peer metro comparison band on the Intelligence Rail [#peer-metro-comparison-band-on-the-intelligence-rail] The [Locus explorer](https://locus.axiomancer.io/explore) Intelligence Rail now includes a **Peer Metros** band that compares the active metro's composite score against its three closest-by-composite peers as horizontal bars plotted against the absolute 0–100 scale. Because every row uses the same scale (instead of being normalized between rows), bar widths are directly comparable — useful for answering "is this metro actually strong, or does it just look strong?" Each peer row links straight to that metro's pulse page, so jumping into deeper context for a comparable market is one click away. No action is required on your part. ## Nearby POIs collapsed into an accordion in the explorer sidebar [#nearby-pois-collapsed-into-an-accordion-in-the-explorer-sidebar] The Nearby POIs list in the [Locus explorer](https://locus.axiomancer.io/explore) sidebar is now collapsed into an accordion by default. POI is supporting due-diligence detail rather than a primary signal, so collapsing it keeps the at-a-glance Nearby summary badges and Crime Safety indicator in view without the long POI list pushing them off-screen. Expand the accordion to see the full list of nearby points of interest. No action is required on your part. ## Score sparkline and signal waterfall on the selected-cell panel [#score-sparkline-and-signal-waterfall-on-the-selected-cell-panel] The selected-cell card at the top of the [Locus explorer](/locus/explorer#selected-cell) Intelligence Rail now shows two glanceable visualizations alongside the composite number. A 90-day score sparkline traces the cell's composite trajectory with a trend-colored stroke — emerald rising, red declining, dim flat — and renders dashed at reduced opacity (with the label *90-day trajectory (estimated)*) when the underlying series is a synthetic flat-trend stand-in for a cell with no real history, so estimated lines are distinguishable from real measurements. A signal-contribution waterfall plots the cell's eight [signal groups](/locus/scoring-conventions) as horizontal bars sorted by score, with tier-colored fills and low-confidence groups dimmed and labeled in a tooltip. The two together replace the previous "what does the composite mean?" narrative with a comparison readers can interpret at a glance, while the full sub-signal breakdown stays available in the left sidebar's score panel for users who want to drill in. No action is required on your part. ## Intelligence rail alongside the Locus explorer map [#intelligence-rail-alongside-the-locus-explorer-map] The [Locus explorer](https://locus.axiomancer.io/explore) now leads with intelligence, not geometry. The map narrows to about a quarter of the viewport width on large screens, and a new **Intelligence Rail** fills the rest with live alerts, top movers, monitored locations, and a metro-pulse snapshot — sourced from the same data that powers the signed-in dashboard. The cell-level score breakdown still lives in the left sidebar when you click a hex. A new mode toggle in the top-right of the map flips between the integrated view and the previous full-bleed map. Append `?mode=fullscreen` to the URL to land directly in the original sidebar-plus-large-map layout. Below the large breakpoint, the rail is hidden and the map fills the page so mobile and tablet keep a map-first layout. ## National activity mini-map on the Locus dashboard [#national-activity-mini-map-on-the-locus-dashboard] The signed-in [Locus dashboard](https://locus.axiomancer.io/dashboard) now opens with a national activity mini-map between the page header and the stat cards, rendering the same 90-day heatmap as the [explorer](https://locus.axiomancer.io/explore) so the dashboard preview and the deep-dive read as one continuous surface. Click anywhere on the map to land in the explorer at that location with the score panel ready, instead of a generic map view, and use the **Open Explorer** button in the top-right for the full-map handoff. Heatmap palette and weight stops match the explorer exactly, so colors read identically across both surfaces. No action is required on your part. ## Tiny tracts excluded from Fastest-Growing by Population ranking [#tiny-tracts-excluded-from-fastest-growing-by-population-ranking] The public [Fastest-Growing Neighborhoods (Population)](/locus/mcp-server) ranking now filters out census tracts with fewer than 1,000 residents in the prior ACS vintage. Small-denominator tracts could otherwise dominate the list with mathematically true but practically meaningless percentages — for example, an industrial-to-residential conversion that grew from 62 to 2,382 residents would surface as +3,741% growth and outrank every actual neighborhood. The threshold keeps the ranking reflective of where real population is moving rather than where reclassifications happened. Column labels and the list description have been clarified to match. No action is required on your part. ## Nearby POIs collapsed by default on the explorer sidebar [#nearby-pois-collapsed-by-default-on-the-explorer-sidebar] The **Nearby POIs** list in the [Locus explorer](/locus/explorer) left sidebar now opens as a collapsible accordion that starts closed when you select a cell, so the long point-of-interest list no longer pushes the at-a-glance signal counts off-screen. POI is a supporting due-diligence detail rather than a primary nav element — most users only need to scan it after the higher-level signals already decide whether a cell is worth a closer look. The **Nearby intelligence summary** badges and the **Crime safety** indicator stay pinned above the accordion and continue to render without a click, so the headline counts (eateries, services, recreation, retail, and the safety read) remain visible the moment a cell is selected. Click the row labelled **Nearby POIs** — which now also shows the count of POIs available, e.g. *15 shown* — to expand the full styled-tile list with photos, distance, ratings, and the per-POI detail expander. Re-clicking collapses it again. No action is required on your part. ## Equasis enrichment runs that hit a per-account daily cap no longer log as failures [#equasis-enrichment-runs-that-hit-a-per-account-daily-cap-no-longer-log-as-failures] The Railway worker that drives [vessel metadata enrichment](/overwatch/api/vessels) from Equasis was logging `ingestion_logs.status = 'failed'` whenever an account hit its daily query cap mid-cycle, even though hitting the cap is normal rate-limit behavior — not a real failure. The cap-exhausted exception was falling through to the fatal-error path that's reserved for actual breakage (login failure, network error, parser regression). Twenty-eight hours of monitoring data showed roughly 1,685 misclassified `failed` rows against 737 genuine successes, so the failure metric on the [status page](/overwatch/status-page) and any alerting wired to `ingestion_logs` was reading mostly noise. Cap-exhausted runs now write `status = 'success'` with `metadata.skipped = true`, `metadata.reason = 'account_daily_cap'`, and `records_stored = 0` — mirroring how the all-accounts-cap path was already handled. Filter on `metadata.skipped` if you want to exclude skipped rate-limit cycles from throughput counts; otherwise, expect the failure rate on enrichment runs to drop sharply at the next cycle without any real change in delivered enrichment data. No action is required on your part. ## SAR fusion no longer biases `risk_score` downward when no radar observation was attempted [#sar-fusion-no-longer-biases-risk_score-downward-when-no-radar-observation-was-attempted] *Historical implementation record: launch-supported chokepoint confirmation is currently AIS-only, and the [Sentinel endpoint](/overwatch/api/sar-coverage) reports catalog metadata without detecting vessels or confirming transits.* The Dempster–Shafer Yager fusion inside `verify-dark-fleet-sar` previously placed `0.7` belief mass on `Lawful` whenever the SAR pixel detector returned `null` — i.e. whenever a SAR check wasn't even attempted (low or medium SAR-coverage potential, missing Copernicus credentials, or a `detectShips` exception). Because the fusion always combined that mass with the AIS prior, every event without a SAR observation came out with a fused `risk_score` lower than its pre-fusion AIS score, systematically pulling unscored events away from `high` and `critical`. At the time of this release, fusion was changed to distinguish three cases. If `pixelDetection` was `null` (no observation attempted), SAR contributed pure ignorance (`mass(L,D) = 1.0`), so the fused score equaled the AIS score. If a strong CFAR detection landed (`maxConfidence > 0.6`), SAR was described as corroborating the dark-event signal proportional to its confidence. If a detection ran but returned weak pixels, the lawful lean was reduced from `0.7` to `0.3` to account for cloud cover, scene-edge clipping, and side-lobe artifacts common in real Sentinel-1 scenes. The release noted that the latent bug would otherwise have started biasing scores at the next 08:00 UTC sweep as the accompanying [`risk_tier` recalibration](#dark-event-risk_tier-thresholds-re-calibrated-against-the-production-score-distribution) fed roughly 1,700 `high`+`critical` events into the then-described fusion path. At the time of this release, consumers of `risk_score` from `/api/v1/risk/events`, `/api/v1/risk/vessels`, or the `dark_event` webhook were told to expect `high` and `critical` events with no SAR observation to settle at their pre-fusion AIS values rather than a depressed fused value. Events reported with strong SAR detections were described as surfacing at `risk_score = 100`. That paragraph records the then-described implementation, not today's product contract. For supported behavior now, see the [current chokepoint operating boundary](/overwatch/methodology/chokepoint-transits#current-operating-boundary); [Risk tiers](/overwatch/api/risk#risk-tiers) owns the tier semantics. ## Dark event `risk_tier` thresholds re-calibrated against the production score distribution [#dark-event-risk_tier-thresholds-re-calibrated-against-the-production-score-distribution] *Historical implementation record: references below to a SAR verification queue do not describe a currently supported production capability. See the [current AIS-only boundary](/overwatch/methodology/chokepoint-transits#current-operating-boundary).* This release re-calibrated the `risk_tier` cutoffs applied to every dark event so the `high` and `critical` buckets would fire. The original thresholds (`low` ≤ 25, `medium` ≤ 50, `high` ≤ 75, `critical` > 75) assumed the 13 risk factors would compound — sanctions match plus STS involvement plus identity manipulation plus a high-risk flag — but most real dark events were isolated AIS gaps where those columns were zero, so the score formula's effective ceiling landed well under the old `high` boundary. Across 26,326 production events, the then-observed distribution was min 5, p50 12, p90 23, p95 27, p99 30, max 42, which meant **zero** events scored `high` and the release's `verify-dark-fleet-sar` pipeline was reported as starved despite the SAR infrastructure described at the time. The release set the thresholds against those percentiles: `low` ≤ 15 (\~p65), `medium` ≤ 25 (\~p65–p93), `high` ≤ 35 (\~p93–p99.5), `critical` > 35 (top \~0.5%). A backfill at the time shifted the reported distribution from 24,624 / 1,702 / 0 / 0 to 18,888 / 5,736 / 1,683 / 19, which was described as feeding roughly 1,700 `high`+`critical` events into the then-planned SAR verification run. At the time, consumers filtering `/api/v1/risk/events`, `/api/v1/risk/vessels`, or the `dark_event` webhook by `risk_tier` were told to expect `high` and `critical` results where those filters had previously returned nothing, with roughly the top half of the prior `medium` population moving into `high`. The release described each event's numeric `risk_score` as unchanged and only the tier-bucket boundaries as moving. See [Risk tiers](/overwatch/api/risk#risk-tiers) for the current table and rationale. ## Global vessel density by type, bucketed into daily H3 cells [#global-vessel-density-by-type-bucketed-into-daily-h3-cells] Overwatch now ships a global vessel density surface built on a daily H3 resolution-8 (\~0.74 km² per cell) matview joined from `ais_positions` to vessel type. Per-IMO-per-hour bucketing means vessels broadcasting every 10 seconds don't swamp vessels broadcasting hourly, so density reflects time-on-station rather than ping cadence — useful for spotting traffic corridors, anchorage clusters, and class-specific hot spots on a given day. Query it via the new [`GET /api/v1/density`](/overwatch/api/density) endpoint with `type` (defaulting to `bulk_carrier`, or `all` to aggregate across types) and `day` (defaulting to yesterday UTC) parameters. The matview holds a rolling 30-day window and is refreshed nightly at **02:00 UTC** after the previous day's bucket closes. A new `/dashboard/density` page in the Overwatch app shows per-type rollups and the top H3 cells alongside a freshness indicator from the underlying `derived_views_freshness` ledger. No action is required on your part. ## Faster vessel popup loads on the live map [#faster-vessel-popup-loads-on-the-live-map] Clicking a vessel on the [Overwatch](/overwatch) live map now opens the popup card noticeably faster, especially when the live weather provider is slow to respond. The vessel context endpoint that powers the popup previously waited up to \~4.5 s for the upstream live-weather fetch to resolve before falling back to the cached `port_weather` snapshot — so a degraded weather upstream pushed total popup latency past 4.5 s even though a usable cached value was available the whole time. The endpoint now runs the live fetch and the cached fallback concurrently and returns whichever resolves first with usable data, so popup latency is bounded by the faster of the two paths instead of the sum. No action is required on your part — the speedup applies automatically the next time you click a vessel. ## Improved vessel icons on the live map [#improved-vessel-icons-on-the-live-map] Vessel markers on the [Overwatch](/overwatch) live map now use elongated triangles that match the industry-standard silhouette you see on VesselFinder and MarineTraffic. The narrower, bow-forward shape makes it easier to read heading direction at a glance. Vessels are also more visible at world and regional zoom levels, so you can spot traffic patterns without needing to zoom in. ## Live map now features the Port of Long Beach [#live-map-now-features-the-port-of-long-beach] The default hero map location has moved from the Bosphorus Strait to the Port of Long Beach, giving you an immediate view of one of the busiest container ports in the Western Hemisphere when you first land on Overwatch. ## Tiny tracts no longer dominate the Fastest-Growing by Population ranking [#tiny-tracts-no-longer-dominate-the-fastest-growing-by-population-ranking] The public [**Fastest-Growing Neighborhoods (Population)** ranking](/locus/mcp-server) now filters out census tracts with fewer than 1,000 prior residents, so small-denominator anomalies — for example, an industrial-to-residential conversion that grew from 62 to 2,382 people and showed as +3,741% — no longer dominate the leaderboard. The list now reflects what a reader looking for "fastest-growing neighborhoods" actually expects: meaningful population growth in inhabited areas. Column labels and the list description were sharpened to match — *Population Change % (5-year ACS)*, *Population (latest vintage)*, *Population (5 years prior)* — so it's clearer that the percentage is a roughly 5-year delta rather than a single year. The composite **Fastest-Growing Neighborhoods (Axiom Composite)** list is unaffected. No action is required on your part. ## Layer integration count corrected to 40+ across marketing surfaces [#layer-integration-count-corrected-to-40-across-marketing-surfaces] The Layer landing page, FAQ answer, and Starter plan feature list now consistently describe the [integration catalog](/layer/integrations/overview) as **40+ integrations** rather than the previous 80+ claim. The hero and integrations wall were updated in an earlier pass; this followup catches the FAQ on the marketing route, the landing-page mirror copy, and the Starter pricing card so every public surface reports the same number. The catalog itself is unchanged — the connectors you can actually configure under [Settings → Integrations](/layer/integrations/overview) are the same as before, only the marketing claim was inflated. No action is required on your part. ## Faster Layer dashboard load times [#faster-layer-dashboard-load-times] The Layer [dashboard](https://app.axiomlayer.io/dashboard) now loads roughly **450–1200 ms** faster on first paint. The page previously fetched its hardware costs, employee costs, and security discovery panels in three sequential round-trips before rendering; those calls now run in parallel, so total time-to-first-byte is bounded by the slowest single fetch instead of the sum of all three. The [assets](/layer) listing page also fetches a narrower column set tailored to the table view, avoiding pulling raw payload and wide metadata blobs over the wire on large tenants. No action is required on your part — the speedup applies automatically the next time you load the dashboard. ## Dedicated AI Usage page powered by RouteShift [#dedicated-ai-usage-page-powered-by-routeshift] Layer now has a dedicated **AI Usage** entry in the dashboard sidebar, between **Hardware** and **Renewals**, for tracking LLM spend per employee across OpenAI, Anthropic, Google, and other providers. The page introduces [RouteShift](https://routeshift.io) — the LLM proxy gateway behind Layer's AI cost tracking — with a one-click **Open RouteShift** handoff for managing per-employee keys, smart routing, savings, and live analytics (cache hit rate, p95 latency, error rate, and savings reporting on daily, weekly, or 24-hour windows). Per-employee spend roll-up directly inside Layer is on the roadmap; until then, the existing per-person, department, and provider ROI views remain available via the [AI usage tracking](/layer/ai-usage-tracking) feature. No action is required on your part. ## Demo mode for fully-populated synthetic workspaces [#demo-mode-for-fully-populated-synthetic-workspaces] Layer organizations can now be flagged as demo tenants, turning the workspace into a fully-populated synthetic environment for prospects, training, and internal walkthroughs. A demo organization renders a pink **Demo data** banner under the cross-product bar on every dashboard page and exposes a new **Demo mode** card in [Settings](/layer/demo-mode#reset-demo-data) with a one-click **Reset demo data** action. Resetting wipes nine tenant-scoped tables in foreign-key order and re-seeds them with 60+ SaaS apps across productivity, dev, security, compliance, finance, HR, marketing, sales, and AI categories, 12 months of monthly spend per app, 18+ contracts spread across the next 12 months of renewals, 12 months of AI usage across OpenAI, Anthropic, and GitHub Copilot, plus a realistic mix of active and `needs_reauth` integration connections. Reset is admin-gated and the server hard-refuses unless the organization is explicitly flagged as demo, so real customer tenants can never be wiped through this endpoint. See [Demo mode](/layer/demo-mode) for the full walkthrough. No action is required on your part. ## Integrations page now reflects "Connected" status after a successful save [#integrations-page-now-reflects-connected-status-after-a-successful-save] Connecting an [integration](/layer/integrations/overview) — Google Workspace, Microsoft 365, Okta, Slack, GitHub, or any other connector that uses OAuth or a credential form — could previously leave the catalog card stuck on **Connect** even after the OAuth callback or credential form had successfully written the connection row. The connection itself was saved correctly and would sync data, but the **Integrations** page reread the catalog under a user-scoped session that was being filtered out by row-level security, so the card never flipped to **Connected** and re-clicking it would attempt to connect again from scratch. The integrations catalog now reads connection status through a workspace-scoped server path that has authoritative tenant context, matching the path the [OAuth callback](/layer/integrations/overview) already uses to write the row. Cards correctly render **Connected**, **Needs reauth**, or **Connect** the first time the page loads after a successful save, and the disconnect and re-sync actions are available immediately. No action is required on your part — the status will show correctly the next time you open the [Integrations page](https://app.axiomlayer.io/integrations). ## Explicit workspace setup step on first sign-in [#explicit-workspace-setup-step-on-first-sign-in] Layer no longer auto-creates a workspace named after your email domain when a new user reaches the dashboard, an [integration](/layer/integrations/overview) connect callback, or the free [shadow IT scan](/layer/integrations/google-workspace) without a workspace already set up. Previously, signing in could silently land you as the owner of a brand-new "Gmail" or "Acme" workspace based on your email — a path that could cross-pollute identity in invitee and SSO flows. New users without a workspace now go through a short **Create your workspace** step that asks for an explicit workspace name before continuing. Existing workspaces, sign-ups that already include a workspace name, and users invited into an existing workspace are unaffected. See [Getting started](/layer/getting-started). No action is required on your part. ## Per-vessel ETA and route-waypoint forecasts [#per-vessel-eta-and-route-waypoint-forecasts] Every vessel currently in transit — with a recent AIS position, a declared destination, and clear of any port zone — now has an hourly route forecast that projects an eight-point great-circle arc from the vessel's current position to its destination port, with an ETA distribution (p10 / p50 / p90) at each waypoint. Forecasts refresh hourly and fall back to a per-class typical cruise speed when a vessel's reported speed is too low to be predictive (for example, a stopped vessel that hasn't yet departed). Use it to anticipate arrival windows, plan berth assignments, and surface vessels likely to slip their declared ETA. See the [forecasts API](/overwatch/api/forecasts) for query patterns. ## Expected arrivals and voyage-times dashboard panels [#expected-arrivals-and-voyage-times-dashboard-panels] The data behind per-vessel route forecasts and voyage time-allocation now has dedicated dashboard surfaces in the Overwatch app. The forecasts page at `/dashboard/forecasts/[port]` now includes an **Expected Arrivals** panel that lists vessels forecast to arrive at the port inside a rolling 7-day window, with the ETA p50 and the p10/p90 spread shown as a "window" column so you can see at a glance which arrivals are tightly bounded versus loosely projected. The new `/dashboard/[port]/voyage-times` page renders per-visit stacked bars (approach / anchor wait / berth / idle other), median summary cards, and a 50-row drill-down table — useful for comparing turnaround efficiency across recent visits at a single port. Both panels share the dashboard's terminal-style chrome and gracefully empty-state when the underlying data hasn't been populated yet. See the [forecasts API](/overwatch/api/forecasts) and [vessel visits API](/overwatch/api/vessels) for the underlying queries. ## Voyage time-allocation reports per port visit [#voyage-time-allocation-reports-per-port-visit] Every closed [vessel visit](/overwatch/api/vessels) now carries a sibling time-allocation breakdown that splits arrival → departure into hours spent on **approach**, **anchor wait**, **berth**, and **idle other** — answering the "where did the time actually go?" question that aggregate berth hours alone couldn't. Allocations are computed on every departure close and a one-time backfill is populating historical visits. Useful for benchmarking turnaround efficiency, attributing congestion to anchor versus berth bottlenecks, and quantifying how much of a long visit was real loading work versus waiting offshore. ## Stripe checkouts now reliably activate paid Overwatch plans [#stripe-checkouts-now-reliably-activate-paid-overwatch-plans] Customers completing a paid Overwatch checkout could previously remain on the free plan after a successful Stripe payment. The webhook handler claims an idempotency row before applying side effects (so a Stripe retry of the same `event.id` doesn't re-run the upgrade), but the underlying `processed_stripe_events` table was missing in the production database. The insert silently failed, the handler treated every webhook as a duplicate, and the matching `subscriptions` row was never written — so checkout completed on Stripe's side but the account stayed on the free tier. The table is now in place, every `checkout.session.completed`, `customer.subscription.updated`, and `customer.subscription.deleted` event applies its side effects exactly once, and Stripe retries are correctly deduplicated rather than skipped. If you completed a paid checkout recently and your account stayed on the free plan, contact support — or re-trigger entitlement sync from your billing portal — and the correct plan and `current_period_end` will populate. No action is required if your subscription is already showing the correct plan. ## Watchlist-scoped vessel-to-vessel near-pass detection [#watchlist-scoped-vessel-to-vessel-near-pass-detection] [Watchlist](/overwatch/api/watchlist) members now have a dedicated near-pass detector that flags any other vessel passing within a configurable distance of a watchlist vessel — including underway encounters that the existing [ship-to-ship transfer detector](/overwatch/api/risk) deliberately filters out (slow speed, outside port zones, latest-position only). Useful for tracking suspicious rendezvous, fleet-against-fleet contact patterns, and dark-fleet associations that don't match the slow-and-loitering profile of an STS event. Backend RPC ships first; alert-rule integration and a UI surface follow in a later release. # April 29, 2026 (/changelog/2026-04-29) ## Brazilian ANTAQ vessel-call cargo enrichment unblocked [#brazilian-antaq-vessel-call-cargo-enrichment-unblocked] The Brazilian ANTAQ vessel-call feed was carrying 1,902 stored rows with `cargo_tons = NULL` on every one — the Carga.zip enrichment pass that fills tonnage on top of the base call records had been silently failing for weeks, leaving the [cargo validation](/overwatch/methodology/cargo-validation) pipeline with no Brazilian ground-truth to match against. Three concurrent issues were stacking on top of each other: the upsert path was set to `ignoreDuplicates`, so even when Carga.zip later succeeded the existing rows could never be patched with cargo tonnage; Carga.zip fetch failures were going to a `console.warn` instead of `ingestion_logs.error`, hiding the missing-cargo cause from operators and from the [status page](/overwatch/status-page); and a scoping bug in the `axiom_events` emission threw a `ReferenceError` whenever `bulkArrivals > 0`, which was being swallowed by the outer try/catch. All three are fixed in one pass — the upsert now patches existing rows, archive fetch failures surface as real ingestion errors, and the events emission collapses two `.map` passes into one so the scoping issue can't recur. Cargo tonnage will flow into the validation pipeline as soon as the upstream Carga.zip archive is reachable. The current `web3.antaq.gov.br/ea/txt/...` URL pattern is returning 404 across all years; that is being tracked separately as a source-migration ticket and any future fetch failure will surface on the [status page](/overwatch/status-page) instead of disappearing into a console warning. No action is required on your part. ## Score robustness badge on the Explorer cell-detail panel [#score-robustness-badge-on-the-explorer-cell-detail-panel] The [Explorer](/locus/explorer#selected-cell) cell-detail panel now surfaces a **score robustness** badge that tells you, at a glance, whether a cell's [composite score](/locus/scoring-conventions) survives a change in grid resolution. Each cell is classified as `stable_core` (score is consistent across the H3 r7/r8 grid pair — a "consensus core" cell), `ambiguity_shell` (score swings meaningfully between resolutions, so the read is grid-sensitive), or `stable_non_signal` (consistently low signal across grids), with a per-cell `support_stability` value behind the bucket. The classification is derived from the [MAUP H3 ensemble stress test](/locus/scoring-conventions) and is intended as an epistemic-uncertainty signal: a cell scoring 78 in the consensus core is a different read than a cell scoring 78 in the ambiguity shell, even when the headline composite matches. Cells that haven't been re-classified yet render no badge — no fabricated default. The classifier re-runs after every material scoring-engine change. The same fields are exposed on the cell-detail RPC alongside the existing per-cell deltas, percentile rank, demographics, and peer-comparison payloads, so programmatic consumers can read the robustness verdict without an extra round-trip. No action is required on your part — the badge populates as the classifier walks the platform, and the score-panel layout is unchanged for cells without a classification. ## `score_history` daily writes unblocked — `/api/score-trends` and cell sparklines now show real time-series [#score_history-daily-writes-unblocked--apiscore-trends-and-cell-sparklines-now-show-real-time-series] Daily snapshots written to the `score_history` table by the Railway scorer had been silently failing for roughly a month — every row's `gentrification_stage` column was being upserted into a table that never had that column, PostgREST returned `42703` on every write, and a non-blocking error handler was swallowing the rejection without surfacing it. `cell_scores` continued to update on the normal cadence so single-point composite scores stayed correct, but every `score_history`-backed surface was reading off a frozen 354-row snapshot from late March: [`GET /api/score-trends`](/locus/api/discovery-and-intelligence#get-apiscore-trends) returned the same metro and per-cell trend payloads day after day, the [Explorer](/locus/explorer#selected-cell) cell-detail score sparkline rendered the same 90-day trajectory regardless of when it was opened, and the [`axiom_get_score_trends` MCP tool](/locus/mcp-server) returned stale rows. The fix lands the missing column on `score_history` and replaces the silent error swallow with an explicit log so any future schema drift surfaces in the next scorer run instead of going unnoticed for weeks. Score computation itself is still not blocked on `score_history` failures — the daily snapshot is a side effect, not a precondition for `cell_scores` being current — so a future history-write regression will keep current scores flowing while operators are alerted to the broken time-series. Starting from the next nightly scorer pass, `/api/score-trends`, the cell-detail sparkline, and the MCP `axiom_get_score_trends` tool begin accumulating fresh daily rows again. Cells that were scored during the outage window are absent from the time-series for those days; the gap closes as new daily snapshots land. If you consume `/api/score-trends` directly, expect `trend[]` (metro mode) and `snapshots[]` (per-cell mode) to start lengthening by one new `snapshot_date` per day rather than reporting the same dates indefinitely. No action is required on your part — the response shape is unchanged. ## Saved searches and one-click "+ Portfolio" on `/discover` [#saved-searches-and-one-click--portfolio-on-discover] The Locus [discover](https://app.axiomlocus.io/discover) surface now lets signed-in users persist their filter set as a named **saved search** and add any result row to a [portfolio](/locus/api/portfolios) in a single click. A **Save search** button next to **Export CSV** captures the active multi-metro, range, signal-slider, and sort criteria as a JSON blob and writes it to the per-user `saved_searches` table. Each row links back to `/discover?saved=` so re-opening a search re-hydrates its filters with no copy-paste. A new **Saved Searches** panel on the dashboard surfaces the six most recent searches as one-click jump points. Every result row also gains a per-row **+ Portfolio** action that adds the cell to your portfolio. If you don't have a portfolio yet, the action creates one inline; if you have several, you pick which one to add the cell to. Three new endpoints back the surface, all session-authenticated: * `GET /api/saved-searches` — list your saved searches, most recent first. * `POST /api/saved-searches` — create a search with a name and filter blob (8 KB cap, names unique per user, case-insensitive). * `DELETE /api/saved-searches?id=` — remove a saved search you own. Anonymous visitors see `/discover` unchanged — Save search, **+ Portfolio**, and the dashboard panel only render for signed-in accounts. Owner-only row-level security on `saved_searches` enforces access at the database layer; every API also re-asserts `user_id` on each query as defense in depth. No action is required on your part. ## Named portfolios with composite scoring and CSV upload [#named-portfolios-with-composite-scoring-and-csv-upload] Locus now supports **named portfolios** — multiple, independently-named collections of monitored locations under a single account, each with its own composite score, coverage counts, and refresh cadence. Manage them from the new [`/dashboard/portfolios`](https://app.axiomlocus.io/dashboard/portfolios) list page (composite score, member count, above/below-70 split, and last-refresh age per row) and the per-portfolio detail page that drills into the member list. Legacy single-list monitors are unaffected — the new `monitored_locations.portfolio_id` foreign key is nullable, so locations created before today continue to surface on the dashboard exactly as before, and a portfolio deletion sends its members back to the unassigned monitor list rather than removing them. The composite portfolio score is the rounded arithmetic mean of every member's most recent `last_score` and is exposed alongside coverage counters (`member_count`, `scored_count`, `above_threshold_count` for cells at or above 70, `below_threshold_count` for scored cells under 70) and `last_refreshed_at` through a new `get_portfolio_summary(portfolio_id)` RPC. Equal-weight is the deliberate baseline until a weighting dimension is specified — it matches how the flat-monitors dashboard already surfaces `avg_score` and avoids implying a precision the ingest path does not yet support. Four new endpoints back the surface, all session-authenticated: * `GET /api/portfolios` and `POST /api/portfolios` — list owned portfolios with member counts, or create a new one (names are unique per user, case-insensitive, up to 120 characters). * `GET /api/portfolios/{id}`, `PATCH /api/portfolios/{id}`, `DELETE /api/portfolios/{id}` — load summary + members, rename, or drop a portfolio. * `POST /api/portfolios/{id}/members` and `DELETE /api/portfolios/{id}/members?member_id=…` — add a single `{name, lat, lng}` location or up to 500 in one bulk request, or remove one by id. Server-side `latLngToCell` at H3 resolution 8 fills `h3_index` for you. * `POST /api/portfolios/{id}/refresh` — bulk-refreshes every member's `last_score` by re-pulling the latest `cell_scores.composite` for the member `h3_index` set in a single `IN` query against the `general` profile. Cells the nightly scorer has not yet covered remain at `NULL` and are reported in the response as `refreshed` (touched) vs. `scored` (had a fresh value). * `POST /api/portfolios/{id}/upload` — bulk CSV import. Accepts `text/csv` directly or `application/json {csv: "..."}` so the UI can post a textarea paste without `FormData`. Header detection picks `lat,lng` (or `latitude,longitude`) when present; otherwise it expects an `address` column and geocodes via the Census one-line geocoder with a 4-way concurrent worker pool and a 6-second per-row timeout. Each upload is capped at **500 rows**, and the response returns a per-row `{rowIndex, status: "inserted" | "geocode_failed" | "invalid", reason}` array so the UI can render a result table for partial failures. ```bash # Create a portfolio curl -X POST https://app.axiomlocus.io/api/portfolios \ -H "Content-Type: application/json" \ --cookie "$LOCUS_SESSION" \ -d '{"name": "Sunbelt QSR Sites"}' # Bulk CSV upload (lat/lng or address) curl -X POST https://app.axiomlocus.io/api/portfolios//upload \ -H "Content-Type: text/csv" \ --cookie "$LOCUS_SESSION" \ --data-binary $'name,address\nDowntown Phoenix,100 N Central Ave Phoenix AZ\nMidtown Atlanta,1100 Peachtree St NE Atlanta GA' # Refresh scores for every member in one round-trip curl -X POST https://app.axiomlocus.io/api/portfolios//refresh \ --cookie "$LOCUS_SESSION" ``` Row-level security on `portfolios` enforces owner-only access at the database layer, and every API also re-asserts `user_id` on each query as defense in depth. No action is required if you only consume Locus data through the public, versioned [`/api/v1/locus/portfolios` reference](/locus/api/portfolios) — that surface is unchanged. The new dashboard endpoints are additive and complement the [`saved=true` portfolio export](/changelog/2026-04-29#portfolio-level-csvjson-export-via-savedtrue) shipped alongside this release. ## Business Licenses dashboard with metro-spanning search and CSV export [#business-licenses-dashboard-with-metro-spanning-search-and-csv-export] A new [`/business-licenses`](/locus/business-licenses) surface lands in the Locus app today, providing a record-by-record search over the normalized business-license catalog across 15 U.S. metros (Chicago, Philadelphia, NYC, Denver, Austin, Portland, Atlanta, Los Angeles, San Francisco, Seattle, Houston, Phoenix, Las Vegas, Miami, Boston). Filter by metro, address substring, NAICS prefix, and pioneer-tier classification (`Pioneer` / `Advanced` / `Mature` / `Dormant` / `None`); sort by `source_loaded_at`, `occurred_at`, or `metro_slug`; and click the maps icon on any row with coordinates to deep-link into Google Maps. Active filters reset pagination automatically, and a one-click **Reset filters** link clears all active criteria. The page is a thin client over a single new endpoint, [`GET /api/business-licenses/search`](/locus/business-licenses#api), which paginates at 50 per page in the UI and caps at 200 per call via the API. **Export CSV** in the filter bar downloads the currently visible page as `business-licenses.csv` with `Source ID, Metro, Address, NAICS, Pioneer Tier, Loaded At, Close Date` columns, honoring active filters and sort. The endpoint requires an authenticated Locus session and returns `401 Unauthorized` otherwise. See the [Business licenses reference](/locus/business-licenses) for the full filter, column, and API parameter table. ## ZBA Decisions dashboard launches with NYC and Philadelphia coverage [#zba-decisions-dashboard-launches-with-nyc-and-philadelphia-coverage] A new [`/zba-decisions`](/locus/zba-decisions) surface in the Locus app makes Zoning Board of Appeals decisions searchable across four jurisdictions: **Chicago**, **Boston**, **NYC**, and **Philadelphia**. NYC ingestion runs against the city's Socrata open-data portal and Philadelphia against OpenDataPhilly's Carto API, both as dedicated upstream collectors with date-column and field-mapping configurations matched to each portal — so refresh cadence tracks the underlying source (typically daily for NYC, several times per week for Philly). Chicago and Boston continue on the existing structured + PDF-decision parsers. Filters cover jurisdictions (multi-select), case number / address combined search (single input matched against either column), outcome (`Approved`, `Denied`, `Granted`, `Granted with Conditions`, `Pending`, `Withdrawn`), variance-type substring, and an inclusive `decision_date` range. Sorting defaults to `decision_date` descending so the most recent rulings lead. Each row's external-link icon opens the original portal record or PDF in a new tab when a `source_url` is present. **Export CSV** writes `Case Number, Jurisdiction, Address, Variance Type, Outcome, Decision Date, Conditions` (conditions truncated to 200 characters) for the visible page. The page is backed by [`GET /api/zba-decisions/search`](/locus/zba-decisions#api). The endpoint requires an authenticated Locus session and returns `401 Unauthorized` otherwise. See the [ZBA decisions reference](/locus/zba-decisions) for the full filter, column, and API parameter table. ## COLREGS compliance scoring with counterfactual deficit [#colregs-compliance-scoring-with-counterfactual-deficit] Every non-compliant [pairwise encounter](/overwatch/methodology/encounter-extraction) now lands a row in a new `colregs_encounters` table with a per-encounter compliance score. The principal field is `compliance_deficit_nm` — a *counterfactual lateral distance* between the give-way vessel's actual position at CPA and where it would have been under the minimum-effort compliant maneuver. A vessel that altered some-but-not-enough has a smaller deficit than one that didn't alter at all, so the score rewards attempted compliance rather than just successful outcomes. Compliant encounters (`compliance_deficit_nm <= 0.05 NM`) are silently dropped so the table stays a worklist of failures rather than a scoreboard of every encounter. Each row also resolves the canonical `encounter_type` (`head_on` / `overtaking` / `crossing` / `mixed`), the `give_way_imo` and `stand_on_imo` (`NULL` when role probabilities are within a `0.10` ambiguity band), the `required_starboard_deg` minimum alteration the give-way vessel should have made, and both vessels' `actual_starboard_deg_*` so head-on (Rule 14: both alter starboard) is fully captured. The safe DCPA threshold the solver targets is contextual — `0.5 NM` open sea, `0.2 NM` channel/TSS/approach, `0.1 NM` anchorage — and is recorded per row as `safe_dcpa_threshold_nm`. A new `score-colregs-compliance` Edge Function runs hourly at minute `:17` (ten minutes after the encounter extractor), with a primary key on `encounter_id` so re-runs are idempotent. A backfill driver, `scripts/backfill-colregs.mjs`, fills any historical window in 6-hour chunks. The schema, algorithm, query patterns, and current limitations — `ghost_inference_vector` is reserved for a follow-up that needs a maneuver-prediction model, and `pairwise_encounter.context_tag` is not yet populated, so every encounter currently falls back to the `open_sea` `0.5 NM` threshold — are documented in the new [COLREGS compliance scoring](/overwatch/methodology/encounter-extraction#colregs-compliance-scoring) section. The deficit is intended for analyst triage and forensic ranking — it is not a calibrated COLREGS adjudication, and a non-zero deficit is not a finding of fault. No action is required on your part — the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs continue on the same schema; the new table is additive. ## Rule 17 handoff timestamp on pairwise encounters [#rule-17-handoff-timestamp-on-pairwise-encounters] Every row written to `pairwise_encounter` by the [pairwise encounter extractor](/overwatch/methodology/encounter-extraction) now carries two new fields: `rule17_handoff_ts` (the timestamp at which Rule 17(a)'s "keep course and speed" obligation transitioned to Rule 17(b)/(c)'s "may / must take avoiding action") and `rule17_handoff_trigger` (which gate fired — `giveway_inaction` or `extremis`). Surfacing T\* separately from the [Rule 17 deviation flags](/overwatch/methodology/encounter-extraction#rule-17-deviation-detection) is the operational disambiguation between **premature, unnecessary deviation** (the stand-on vessel broke course before authority transferred) and **required avoidance** (the stand-on vessel was already authorised, or compelled, to act). Two deterministic, geometry-only triggers fire T\* on the canonical give-way side (whichever vessel has the higher mean `give_way_prob` across the encounter epochs), with the earliest match winning: `giveway_inaction` requires `risk_prob > 0.70` **and** `dcpa_nm < 0.5` **and** the give-way vessel's max single-step COG change over the trailing 120-second action window below 5° (Rule 17(b) authority because the give-way vessel is observably failing to keep clear); `extremis` short-circuits when `dcpa_nm < 0.1` (≈200 m) regardless of give-way behaviour (Rule 17(c) compels stand-on action because geometry has already collapsed). The thresholds are exported from `@axiom/core/processing/encounter-extraction` as `RULE17B_RISK_PROB_THRESHOLD`, `RULE17B_DCPA_THRESHOLD_NM`, `RULE17B_ACTION_WINDOW_S`, `RULE17B_GIVEWAY_ACTION_TOL_DEG`, and `RULE17B_EXTREMIS_DCPA_NM` so analyst tooling can probe with non-default values without forking the algorithm. Combine the handoff timestamp with the deviation flags to isolate the most analytically interesting cells — `rule17_handoff_ts IS NOT NULL` AND `rule17_deviation_*` true marks required avoidance after authority transferred; `rule17_handoff_ts IS NULL` AND `rule17_deviation_*` true flags potential premature deviation. A partial index on `rule17_handoff_ts DESC` keeps the analyst worklist query "show me encounters where Rule 17(b)/(c) authority transferred recently" cheap at production fleet size. Both columns ship `NULL` when no trigger fires. The columns ship as additive nullable defaults on `pairwise_encounter`, so there is no migration on your end. Pre/post-handoff deviation magnitudes, a continuous handoff confidence score, per-port and per-corridor handoff-rate rollups, nav-status priors, and TSS / narrow-channel context overrides are deliberately deferred to Phase 2. See the new [Rule 17 handoff timestamp](/overwatch/methodology/encounter-extraction#rule-17-handoff-timestamp) section for the full algorithm, query patterns, and current limitations. No action is required on your part — the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs continue on the same schema; the columns populate from the next hourly run forward. ## Rule 17 deviation flags on pairwise encounters [#rule-17-deviation-flags-on-pairwise-encounters] Every row written to `pairwise_encounter` by the [pairwise encounter extractor](/overwatch/methodology/encounter-extraction) now carries two new pairs of columns: `max_course_change_{a,b}_deg` (largest single-step COG delta observed for each vessel across the encounter, in degrees) and `rule17_deviation_{a,b}` (boolean). The boolean fires when both gates hold for that vessel: the max course change is at least 10° (a meaningful maneuver, not AIS jitter) **and** its mean stand-on probability across the encounter epochs is at least 0.6 (it was the stand-on side often enough that staying on course was the legal expectation). The combination is what makes the flag specifically a Rule 17 signal rather than a generic "vessel turned" indicator — Rule 17(a)(i) requires the stand-on vessel to keep her course and speed, so a stand-on vessel that maneuvers materially is typically reacting to a give-way vessel that failed to keep clear. A partial index over `start_ts DESC` filtered on `rule17_deviation_a OR rule17_deviation_b` keeps the analyst worklist query "show me encounters where a stand-on vessel was forced into action recently" cheap at production fleet size. Both thresholds are exported from `@axiom/core/processing/encounter-extraction` as `RULE17_MIN_COURSE_CHANGE_DEG` and `RULE17_MIN_MEAN_STAND_ON_PROB` so analyst tooling can probe with non-defaults without forking the algorithm. The flags are deterministic and geometry-only — they prioritise which encounters to send to manual COLREGS adjudication, they don't replace it. The columns ship as additive nullable defaults on `pairwise_encounter`, so there is no migration on your end. Counterfactual compliance distance and ghost-encounter back-projection — the rest of the Rule 17 evidence pipeline — are deliberately deferred to a follow-up phase that needs a maneuver-prediction model. See the new [Rule 17 deviation detection](/overwatch/methodology/encounter-extraction#rule-17-deviation-detection) section for the full algorithm, query patterns, and current limitations. No action is required on your part — the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs continue on the same schema; the flags populate from the next hourly run forward. ## Encounter epochs now carry COLREGS rule and role posteriors [#encounter-epochs-now-carry-colregs-rule-and-role-posteriors] Every row written to `encounter_epoch` by the [pairwise encounter extractor](/overwatch/methodology/encounter-extraction) is now annotated with COLREGS-aligned rule posteriors (`p_head_on`, `p_overtaking`, `p_crossing`) and per-vessel role posteriors (`give_way_prob_a`, `stand_on_prob_a`, `give_way_prob_b`, `stand_on_prob_b`). The rule posteriors are normalized to sum to `1` and are derived from epoch geometry alone — reciprocal-course and bow-aligned gates for head-on, parallel-course plus one-forward-one-aft bearings (Rule 13's "more than 22.5° abaft the beam") for overtaking, and the residual mass for crossing. Role posteriors then condition on the rule posteriors: head-on splits 50/50 (Rule 14, no stand-on priority), the overtaker is give-way, and crossing assigns give-way to the vessel with the other on its starboard side. Clean head-on, overtaking, and crossing geometry each push the corresponding rule posterior past `0.85`; ambiguous geometry produces a soft mixture instead of a brittle vote. The columns themselves shipped as nullable on the prior schema rollout, so there is no migration on your end — rows that previously held `NULL` will populate from the next hourly run forward, and any consumer that already reads them gets non-null values without code changes. `p_special_context` (TSS / narrow-channel / RAM context) remains `NULL` for now; it requires TSS polygon ingestion and a `vessels.nav_status` join that have not yet landed, and will populate without a schema change when they do. See the new [Rule and role posterior inference](/overwatch/methodology/encounter-extraction#rule-and-role-posterior-inference) section for the full geometric gates and edge cases. No action is required on your part — the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs continue on the same schema. ## Pairwise encounter extraction now runs hourly in production [#pairwise-encounter-extraction-now-runs-hourly-in-production] [Pairwise encounter extraction](/overwatch/methodology/encounter-extraction) — the algorithm that derives vessel-to-vessel CPA, TCPA, range, closing speed, and bearing-rate geometry from raw AIS positions — now runs as a scheduled Edge Function rather than an ad-hoc invocation against `@axiom/core`. The new `extract-encounters-hourly` cron job fires at minute `:07` of every hour, pulls the trailing 90 minutes of `ais_positions` (a 30-minute overlap with the prior run so encounters straddling the hour boundary are captured end-to-end), generates candidate vessel pairs via H3 resolution-6 spatial buckets with 1-ring neighbour expansion, and upserts results into `pairwise_encounter` (keyed on `vessel_a_id, vessel_b_id, start_ts`) and `encounter_epoch` (keyed on `encounter_id, ts_utc`). Stable upsert keys mean re-running the function over the same window is fully idempotent. A safety cap aborts any run that generates more than 50,000 candidate pairs with a `pair_explosion` error rather than letting a pathological window run away. Each invocation also writes an `ingestion_logs` row with position counts, pairs evaluated, encounters and epochs produced, and the window — visible alongside the rest of the ingestion observability stream on the [status page](/overwatch/status-page). For backfills and re-pulls, a new `scripts/backfill-encounters.mjs` driver chunks a `since → until` range into fixed-length windows (default 60 minutes) and POSTs each chunk to the Edge Function in sequence; a 7-day backfill completes in roughly 10–20 minutes depending on position density. The Edge Function also accepts ad-hoc `since` / `until` overrides on POST so a single window can be re-processed directly with `curl`. See the new [Production pipeline](/overwatch/methodology/encounter-extraction#production-pipeline) section for invocation examples and the spatial pair-generation strategy. No action is required on your part — encounter-derived data on the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs continues on the same schema; the change shows up as fresher coverage and complete historical backfills. ## Portfolio-level CSV/JSON export via `saved=true` [#portfolio-level-csvjson-export-via-savedtrue] [`GET /api/export`](/locus/api/discovery-and-intelligence#get-apiexport) now accepts `saved=true` to scope the export to the caller's saved cells — the cells in their `monitored_locations` portfolio — instead of a full-metro or platform-wide pull. The filter joins to `monitored_locations` on the authenticated user, collects the `h3_index` list, and applies it as an `IN` filter against `cell_scores` so the result respects the existing `composite`-descending order and `limit` cap. It composes with `metro` (e.g. `saved=true&metro=sf` returns only saved cells inside SF) and with `format=csv` or `format=json`. Users with an empty portfolio get a `200 OK` empty payload (`{ "total": 0, "data": [] }` for JSON, an empty body for CSV) rather than a full-table scan. The download filename is tagged `saved` (for example, `axiom-locus-saved-2026-04-29.csv`) so portfolio exports are easy to identify alongside metro pulls on disk. The endpoint continues to require Pro or Team plan entitlement (`bulk_export`); no schema or auth changes on your end. See the updated [`/api/export` reference](/locus/api/discovery-and-intelligence#get-apiexport) for the full parameter table and example invocations. ## Per-signal freshness chips on the Explorer's score panel [#per-signal-freshness-chips-on-the-explorers-score-panel] The cell-detail score panel in the [Explorer](/locus/explorer) now surfaces a **last-refreshed** chip on every row of the signal-contribution waterfall, plus a matching chip beside the score-panel section header. The chip renders a relative age (`now`, `5m`, `2h`, `3d`, `5w`) and is color-coded against the score-refresh SLA — dim under 72 hours, amber from 72 to 168 hours, red beyond a week — so a stale composite score is visually impossible to miss when you're drilling into the waterfall. Hover any chip to see the absolute refresh timestamp and its readable status (for example, *Last refreshed Apr 27, 2026, 9:14 AM · aging (>3 days)*). All eight signal groups currently share a single refresh snapshot — score history updates atomically per cell, so each per-row chip on the same cell shows the same age. The chips repeat per row deliberately: it makes freshness un-missable when scanning the waterfall, and reserves the slot for a future per-signal differential refresh without re-laying-out the panel. The coarser cell-level **staleness tier** (`prime` / `stale` / `unscored`) in the score-panel footer is a separate, longer-window annotation and is unchanged. See [Score freshness chips](/locus/explorer#score-freshness-chips) for the full color-tone table. No action is required on your part. ## `safetyEnvironment` now tracks year-over-year 311 complaint trends [#safetyenvironment-now-tracks-year-over-year-311-complaint-trends] The `safetyEnvironment` signal group on `/api/score` now incorporates a new **Complaint Trend YoY** sub-score that tracks whether 311 complaint density in a cell is rising or falling against the same 30-day window one year ago. The sub-score is computed in-app from the `service_requests_311` rows the scorer already pulls for density and resolution time — counting complaints in the trailing 30 days, counting complaints in the matching 30-day window 335–395 days prior, and emitting the YoY delta `(current − prior) / max(prior, 1)` capped at `+5×`. Negative YoY (complaints down) lifts the cell's safety score; positive YoY (complaints up) penalizes it, with values saturating once the rate triples. Rising 311 density is treated as a Pioneer Stage 1 signal — the same complaint-acceleration pattern that typically precedes pioneer-business clustering by 12–24 months and feeds the [Pioneer Signal](/locus/scoring-conventions#pioneer-signal-and-early-stage-gentrification-indicator) cascade. Complaint Trend YoY contributes 5% of the `safetyEnvironment` group score and surfaces in API responses as a `subScores` entry with `name: "Complaint Trend YoY"` and `source: "AXL-107 (311 YoY)"`. Cells where both the current and prior 30-day windows are empty omit the sub-score and surface `AXL-107 (311 YoY)` under `sourcesMissing` instead of emitting a misleading "improving" signal from a quiet cell. Read it alongside the existing `Complaint Density` and `Complaint Velocity` sub-scores — density is loudness now, velocity is the 30-day change, YoY is the year-on-year direction. See [Complaint Trend YoY](/locus/scoring-conventions#complaint-trend-yoy-axl-107) for the full normalization curve. No action is required on your part — composite and group scores remain on the same 0–100 scale. ## `developmentPipeline` now weights permits by scope and cost tier [#developmentpipeline-now-weights-permits-by-scope-and-cost-tier] The `developmentPipeline` signal group on `/api/score` now incorporates a new **Permit Scope Quality** sub-score that weights every recent building permit by what the permit is actually *for*, not just whether it was issued. Each permit's LLM-extracted `scope_type` (`new_construction`, `addition`, `demolition`, `renovation`, `repair`) and `estimated_cost_tier` are combined into a 0–100 contribution, and the cell's sub-score is the average across the trailing 6-month window. New construction in the highest cost tier trends toward 100; cells dominated by low-cost repairs trend toward 0. The signal is designed to separate cells where permits represent genuine new development from cells where permits mostly reflect maintenance churn — two cells with identical permit counts can now diverge meaningfully on this dimension. Permit Scope Quality contributes 10% of the `developmentPipeline` group score and surfaces in API responses as a `subScores` entry with `name: "Permit Scope Quality"` and `source: "AXL-108"`. Cells where the extractor has not yet annotated any permit will see `AXL-108` listed under the group's `sourcesMissing` instead. See [Development pipeline sub-scores](/locus/scoring-conventions#development-pipeline-sub-scores) for the full weighting table. No action is required on your part — composite and group scores remain on the same 0–100 scale, and `developmentPipeline`'s 0.20 weight in the `general` profile is unchanged. ## Cell score history writes restored, sparkline and `/api/score-trends` flowing again [#cell-score-history-writes-restored-sparkline-and-apiscore-trends-flowing-again] The [`/api/score-trends`](/locus/api/discovery-and-intelligence) endpoint and the **90-day trajectory** sparkline on the [Explorer](/locus/explorer#selected-cell)'s selected-cell panel had been reading from a frozen time-series for the past month. While `cell_scores` continued to refresh daily, the `score_history` table (the snapshot store the sparkline and trends API both read from) had been stalled at the same rowset since late March — so cell-detail sparklines were quietly falling back to their synthetic flat-trend stand-in (the dashed *90-day trajectory (estimated)* indicator), and `/api/score-trends` was returning the same rolling window rather than tracking actual day-to-day movement. Root cause was a schema drift between `cell_scores` and `score_history`: the daily scorer was upserting a `gentrification_stage` column that only existed on `cell_scores`, so every history upsert was being rejected by PostgREST and silently swallowed by an empty error handler. The fix is two-part — a migration adds `gentrification_stage` to `score_history` so the upsert now lands, and the silent error handler is replaced with explicit logging so the next schema or payload drift surfaces immediately instead of disappearing for a month. Cell-level scoring was never affected; the daily snapshot is a side effect of the scorer rather than a precondition for `cell_scores` being current. Real time-series data starts populating from the next scorer run forward for any cell visited that day. Cells that haven't been re-scored since the freeze will pick up history as the nightly job revisits them. No action is required on your part — the affected sparkline rendered its dashed *(estimated)* fallback during the freeze, so consumers of the [`/api/score-trends`](/locus/api/discovery-and-intelligence) endpoint and the cell-detail panel will see the trajectory line transition from estimated to real measurements as new snapshots accumulate. ## Orphaned `ingestion_logs` rows now finalize within 5 minutes [#orphaned-ingestion_logs-rows-now-finalize-within-5-minutes] Edge Functions on Supabase write `status = 'running'` to [`ingestion_logs`](/overwatch/status-page) on entry and `UPDATE` the same row on exit. If a function dies mid-execution — Deno panic, OOM, the platform's 150 s / 400 s wall-clock cap, or the catch-handler `UPDATE` itself failing — the row is permanently stuck with `status = 'running'` and `completed_at = NULL`. Audit during the recent silent-failure verification window found a sizeable backlog of these orphans across four sources (with one upstream alone accounting for the bulk of them), some 12+ minutes old. They poison the silent-failure detector — the detector filters by `completed_at > NOW() - INTERVAL '24h'`, so orphans never enter the window, and a function that *only* orphans (never writes a terminal status) appears to have **zero runs at all**. A new pg\_cron job, `sweep-orphaned-ingestion-logs`, now runs every five minutes. It calls `public.sweep_orphaned_ingestion_logs()`, which finds rows with `status = 'running' AND started_at < NOW() - INTERVAL '5 minutes'` (well beyond the Edge Functions wall-clock cap, so any older `running` row is by definition abnormally terminated) and finalizes them as `status = 'failed'` with `error = 'orphaned by sweeper — function exited without writing terminal status'`. Using `'failed'` rather than introducing a new `'orphaned'` status keeps the existing silent-failure detector and operator dashboards working without changes — orphaned runs now flow into the same failed-count path as any other terminal failure, so an Edge Function that only orphans will surface as a real outage instead of looking dormant. If you query `ingestion_logs` directly to drive an external dashboard or alerting rule, expect to see the sweeper-finalized rows alongside organically-failed runs; you can identify them by the `'orphaned by sweeper'` substring in `error`. No action is required if you only consume Overwatch data through the public APIs. ## Sanctioned-aircraft seed expanded beyond Mahan Air [#sanctioned-aircraft-seed-expanded-beyond-mahan-air] The curated `aircraft_identities` seed that drives Overwatch's [aircraft tracking](/changelog/2026-05-02-weekly) surface — hourly ADS-B ingestion for SDN-listed airframes, joined to high- and critical-tier dark vessel events for cross-modal evasion leads — now covers four additional sanctioned operators alongside the original Mahan Air fleet. Twelve new airframes have been added: **Qeshm Fars Air** (×2, IRGC-QF cargo, OFAC 2019 designation), **Pouya Air** (×2, the rebranded Yas Air, EO 13382 NPWMD), **Air Koryo** (×4, the DPRK state airline, UN 1718 + OFAC + EU), and **Cham Wings / Fly Cham** (×4, Syria SDN airframes that survived the July 2025 Syria revocation; the June 2025 rebrand to "Fly Cham" is itself an evasion-tracking signal). Every ICAO 24-bit hex was verified against a live Flightradar24 airframe page rather than recalled, and each row's `source_uri` points to the OFAC press release, Iran Watch entry, OpenSanctions record, or ARIJ investigation that establishes the SDN-to-airframe link. If you read the public `aircraft_latest_positions` view or the `sanctioned_aircraft_near_dark_event_ports` cross-modal lead view, expect more rows once the next ADS-B poll cycle lands fixes for the new airframes — schema is unchanged, the only difference is broader coverage. The same RLS posture applies (read-all for `anon` and `authenticated`, service-role writes only). A defensive normalization also lowercases any `icao_hex` values that survived earlier deploys with uppercase characters, so primary-key joins against `aircraft_positions` no longer drift on operators that re-registered tail numbers. No action is required on your part. ## Refreshed homepage stats on axiomoverwatch.io [#refreshed-homepage-stats-on-axiomoverwatchio] The hero, platform, and intelligence pages on [axiomoverwatch.io](https://axiomoverwatch.io) now report current production figures instead of last quarter's drift. The hero counter steps up to 31.5M AIS positions, 41,000+ tracked vessels, 369K port events, and 26K dark events; the `/platform` and `/intelligence` pages have been updated to match, and the page-level SEO metadata and `SoftwareApplication` JSON-LD now embed the same numbers so search results and social previews stop quoting stale counts. No action is required on your part. ## AISHub bulk ingestion no longer drops entire batches in dense corridors [#aishub-bulk-ingestion-no-longer-drops-entire-batches-in-dense-corridors] The AISHub poller that backstops the [AIS coverage](/overwatch/ais-coverage) feed was occasionally losing whole cluster fetches in the busiest geographies — most reliably **NW Europe / Channel** (around 1,800 vessels per fire) and **Strait of Hormuz / N Gulf** under contention with the AISStream worker and APRS backfill. The `ais_positions` table carries 12 indexes, and a single bulk insert of that many rows ran the index-update fanout past the database's 60-second statement timeout, so the entire batch was rolled back, the [status page](/overwatch/status-page) **Data pipeline** indicator drifted toward degraded during peak hours, and the matching `ingestion_logs` row for the run showed `status = 'failed'` with everything fetched but nothing stored. The poller now writes both the foreign-key-prerequisite vessels upsert and the `ais_positions` insert in chunks — **200 rows per upsert** and **150 rows per insert** — with a 50 ms breathing pause between chunks and a one-shot retry per chunk on a 200 ms backoff. Vessels and positions are sized differently for two reasons: `ON CONFLICT` upserts are heavier per row than plain inserts, and `ais_positions` carries 12 indexes versus fewer on `vessels`, so the index-update fanout per chunk is roughly 12× larger. `ais_positions` also contends continuously with the AISStream worker for the same index pages, which pushed the original 250-row positions chunk past the per-request timeout in the densest corridors when contention was elevated. The current 150-row positions chunk lands with a comfortable safety margin, and the per-chunk retry absorbs transient lock contention without operator involvement. Each individual statement now finishes well under the per-request timeout budget (the actual ceiling, \~10 s on PostgREST's `authenticator` role, is tighter than the 60 s database-level statement timeout an earlier pass had assumed), and concurrent writers no longer fight for a single 30+ second exclusive lock on the index pages. Per-chunk failures are non-fatal — the next minute's poll picks up the same vessels again, so any loss is bounded. The `ingestion_logs.status` column gained a new value, **`'partial'`**, used when at least one chunk landed but at least one other chunk failed; `'failed'` is now reserved for the case where every chunk fails. Chunk-failure counts are exposed per side of the pipeline as `metadata.chunks_failed` (positions insert) and `metadata.vessel_chunks_failed` (vessels upsert), and the silent-failure detector picks up partial runs through those keys. If you query `ingestion_logs` directly — for example, to drive an external dashboard or an alerting rule — handle `'partial'` alongside `'success'` and `'failed'` (a partial run still wrote real data) and read both `metadata.chunks_failed` and `metadata.vessel_chunks_failed` if you want to count dropped chunks. No action is required if you only consume AIS data through the [vessels](/overwatch/api/vessels) or [density](/overwatch/api/density) APIs — the change shows up as more consistent coverage and fewer gaps in corridor clusters. # April 30, 2026 (/changelog/2026-04-30) ## Scheduled report emails no longer duplicate when cron invocations overlap [#scheduled-report-emails-no-longer-duplicate-when-cron-invocations-overlap] Layer's scheduled report cron — the loop behind the recurring email digests configured under [Plans and billing](/layer/billing) — previously did a `SELECT` of due schedules and then `UPDATE`d each schedule's `next_run_at` after sending. Two cron ticks landing in the same window (a Vercel cron retry, a manual trigger overlapping the regular run, or a multi-region replica firing twice) could both read the same schedule as still-due, both call `sendEmail()`, and both then advance `next_run_at` — leaving recipients with two copies of the same digest in their inbox for that window. Idempotency now lives one level deeper than the schedule row. Before sending, the cron claims a `(schedule_id, scheduled_for)` tuple in a new internal `scheduled_report_runs` table via `INSERT … ON CONFLICT DO NOTHING`, where `scheduled_for` is pinned to the schedule's current `next_run_at`. The unique constraint on `(schedule_id, scheduled_for)` is the gate: a parallel tick that read the same due row attempts the same insert, hits the conflict, and is skipped without calling `sendEmail()`. The first claimer proceeds, sends, marks the run row `sent` with a `completed_at`, and advances `next_run_at` exactly once. Failed sends mark the run row `failed` with the error message, also stamp `completed_at`, and advance `next_run_at` (fail-forward — email delivery is not retried within the same window, so a transient outage doesn't pile up duplicate retries on the next tick). The cron's response payload now carries an additional `skipped` counter alongside `processed`, `sent`, and `failed` so contention is visible in the existing observability surface. A back-to-back invocation against a single due schedule will now report `processed: 1, sent: 1, skipped: 0` on the first call and `processed: 1, sent: 0, skipped: 1` on the second, instead of two sends. The `scheduled_report_runs` table is service-role-only with default-deny RLS — it isn't exposed on any tenant API, and tenant-facing schedule configuration is unchanged. No action is required on your part. Existing schedules continue to deliver on the same cadence; the only observable difference is that overlapping cron invocations no longer duplicate the email. # May 1, 2026 (/changelog/2026-05-01) ## Rate limits and request-size guardrails on sensitive Layer endpoints [#rate-limits-and-request-size-guardrails-on-sensitive-layer-endpoints] A handful of Layer's heavier API surfaces — comments, [contract extraction](/layer/contracts), and the demo-data seed and reset endpoints — now enforce per-tenant rate limits and explicit request-body size caps. Bursts that previously could pile up against the LLM or seed pipeline are now rejected with a clean `429` (rate limited) or `413` (payload too large) response, instead of degrading shared throughput for everyone in the workspace. The limits are sized for normal product use and don't affect typical dashboard or [integration](/layer/integrations/overview) workflows. Programmatic consumers see standard `Retry-After` and `X-RateLimit-Remaining` headers so clients can pace themselves. ## Tighter session enforcement on the dashboard [#tighter-session-enforcement-on-the-dashboard] Layer's dashboard middleware now revalidates every request against the active Supabase session and tenant claim before serving it, closing edge cases where a stale or partially-rotated session could briefly resolve to the wrong workspace after a sign-out, plan change, or workspace switch. Authenticated traffic is unaffected; the only observable difference is that signed-out tabs redirect to `/login` immediately on the next request rather than rendering a cached shell first. ## Stripe webhook processing is now idempotent up front [#stripe-webhook-processing-is-now-idempotent-up-front] Stripe webhook events on [Plans and billing](/layer/billing) are now claimed by event ID at the very start of the handler, before any subscription, invoice, or plan-tier write runs. A duplicate delivery from Stripe's at-least-once retry behavior — common during transient network blips or replays — is recognized and short-circuited cleanly, instead of risking a double-applied subscription update or a redundant ledger write. No action is required on your part. ## One-click Slack OAuth [#one-click-slack-oauth] Connecting Slack to Layer no longer requires creating a Slack app or pasting a bot token. The connector now uses a one-click OAuth flow brokered through Auth0 — click **Sign in with Slack** on the integration card, approve the bot scopes on Slack's consent screen, and you're connected. The same six read-only scopes apply (`users:read`, `users:read.email`, `channels:read`, `groups:read`, `team:read`, `apps:read`), and Layer still never asks for message-content access. Existing tenants on the legacy bot-token flow keep working unchanged — Layer transparently falls back to the previous credential field. Reconnecting through the OAuth flow upgrades the connection automatically. See the updated [Slack integration guide](/layer/integrations/slack). # Week of April 26–May 2, 2026 (/changelog/2026-05-02-weekly) This is a historical release record. Launch-supported chokepoint confirmation is currently AIS-only; Sentinel catalog coverage does not detect vessels or confirm transits. See the [current methodology](/overwatch/methodology/chokepoint-transits). ## This week at a glance [#this-week-at-a-glance] Heavy week across all four products. Overwatch shipped a new Bloomberg-style terminal at [`/dashboard`](/overwatch/getting-started) with two preset modes and a 12-panel HUD, a built-in service [status page](/overwatch/status-page), a public global vessel positions endpoint, per-vessel ETA and [route-waypoint forecasts](/overwatch/api/forecasts) on every vessel in transit, voyage time-allocation reports on every closed visit, watchlist-scoped vessel-to-vessel near-pass detection now wired into [alert dispatch](/overwatch/api/alerts), the then-reported tip-and-cue Sentinel-1 [SAR confirmation](/overwatch/api/sar-coverage) of vessel transits (historical only; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)), user-defined custom geofences, a [vessel density dashboard](/overwatch/api/density) backed by daily, weekly, and monthly H3 layers, course-alteration anomaly detection on underway vessels, made live-map panning instant by loading the full global vessel layer up front, refreshed its live-map vessel icons, and centered the homepage map on the Port of Long Beach. Layer added a dedicated [AI Usage](/layer/ai-usage-tracking) entry in the dashboard sidebar with a one-click handoff to [RouteShift](https://routeshift.io), the LLM proxy gateway behind Layer's AI cost tracking — then expanded it into a three-tab hub with per-employee key minting and per-identity spend attribution. Layer also shipped bulk PDF and image [contract](/layer/contracts) upload with vision-based extraction, an admin **Audit log** dashboard backed by a 6-year immutable ledger, an additional **Sign in with Auth0** option on the login page, hardened Stripe webhook processing on [Plans and billing](/layer/billing), and rolled out a self-contained demo mode for evaluation tenants. Layer, Codex, and the Axiomancer Labs parent site all picked up proper social previews and search-engine discoverability. Overwatch also surfaced the cross-product bar everywhere, sped up its hero video, backfilled cargo estimates, and tightened its data-source health alerting. Locus tailored its ranking pages to the columns that drive each list, replaced the metro-scoped explorer overlay with a national activity heatmap, added a matching mini-map to the signed-in dashboard, and reframed the explorer around a cell-aware intelligence rail of live alerts, top movers, and monitored locations alongside the map — with a per-cell sparkline and signal-contribution waterfall when you click a hex — shipped two new public rankings (Fastest-Growing by Population and Most Building Permits) and two new Analyst+ momentum lists (Fastest-Rising and Fastest-Falling Cells) with leaderboard quality fixes, sped up `/api/score` by running supplemental fetches in parallel, hardened its first-load path and POI ingestion budgets, sharpened neighborhood resolution to match what you see on Google Maps (including support for islands and exclaves), shipped a faster home page hero, and locked down the free Location Report request form behind CAPTCHA and double opt-in. Layer cleaned up its sign-up flow so first-touch and email/password sign-ups no longer dead-end, and the parent site got a faster initial paint. ### New features [#new-features] * **Overwatch**: New Bloomberg-style terminal landing at [`/dashboard`](/overwatch/getting-started). A fixed-viewport HUD with two preset modes — **TRADE** for commodity flow tracking and **SANC** for sanctions analytics — each laying out 12 live-data panels (port-flow heatmap, live vessel mini-map, export forecasts, berth utilization, commodity tape, trade-flow tracker, active alerts, dark-fleet map, anomaly queue, risk profiles, verification queue, and a recent-events stream). `F1`–`F12` jump to the equivalent dashboard sub-route, and `⌘K` (or `Ctrl+K`) opens a command palette. Pin actions reuse your existing watchlist. A simplified mobile view is shown on small screens. The previous landing page is preserved at `/dashboard/overview` and all 24 dashboard sub-routes still work as before. * **Overwatch**: Built-in service [status page](/overwatch/status-page) showing real-time health for database connectivity, AIS data freshness, ingestion pipeline, and visit pipeline, with each service's current state and a 24-hour visual timeline so intermittent issues are easy to spot. Health checks run every five minutes, three consecutive failures trigger an automatic alert, and a programmatic health endpoint is available for external monitoring tools. Visit it from **Dashboard > Status**. * **Overwatch**: New public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint returns a global GeoJSON `FeatureCollection` of the latest position for every tracked vessel (\~18K) in a single request. No auth required, CDN-cached for five minutes, with optional `type` filter and a bounding box. Use it to power your own live map, heatmap, or periodic dashboard refresh instead of paging port-by-port. * **Overwatch**: Multi-recipient verified email delivery on [alert channels](/overwatch/api/alerts). `PUT /api/v1/alerts/channels` now accepts up to five recipient addresses on the email channel. Your own account email is auto-verified; every other address receives a one-time confirmation link with a 24-hour expiry, and only verified recipients are dispatched to — both for `/channels/test` and for the production watchlist cron. Per-pair guards (5-minute resend cooldown, 10/24h hard cap) and a 3-per-hour limit on test sends prevent the channel from being used as a phishing relay against arbitrary inboxes. Single-recipient self-only delivery, the previous interim mitigation, is removed. * **Overwatch**: New daily ingestion of 41 [FRED](https://fred.stlouisfed.org/) economic series across rates, industrial production, capacity utilization, orders, inventories, housing, freight, commodity prices, CPI/PPI, employment, trade, and financial conditions. Observations are vintage-aware — FRED revisions are recorded as new prints rather than overwriting prior values — so historical queries are reproducible. The fetch runs at 14:00 UTC, idempotent on each run. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: Sentinel-1 SAR ship detections from each dark-fleet verification run were reported as persisted alongside the dark events they confirmed, instead of being discarded after the scene-level CFAR pass. The current [Sentinel endpoint](/overwatch/api/sar-coverage) exposes catalog metadata only and does not run that detector. * **Overwatch**: Per-vessel ETA and route-waypoint forecasts on every vessel currently in transit, with a new **Expected Arrivals** dashboard panel on `/dashboard/forecasts/[port]` listing vessels forecast to arrive in a rolling 7-day window with ETA p50 and p10/p90 spread. An hourly run projects an eight-point great-circle arc from the vessel's current position to its declared destination port, with an ETA distribution (p10 / p50 / p90) at each waypoint, falling back to a per-class cruise speed when reported speed is too low to be predictive. Use it to anticipate arrival windows, plan berth assignments, and surface vessels likely to slip their declared ETA. See the [forecasts API](/overwatch/api/forecasts). * **Overwatch**: Each [vessel detail page](/overwatch/api/vessels) now renders the active route forecast inline. A four-stat strip pins distance to go, current speed, ETA p50, and the p10→p90 window above an interactive map showing the eight-waypoint great-circle projection with hover tooltips for per-waypoint ETAs, plus a compact waypoint table beneath. The panel hides itself for vessels not currently in transit (no recent fix or no declared destination) so non-transiting ships don't show an empty card. * **Overwatch**: Voyage time-allocation reports on every closed [vessel visit](/overwatch/api/vessels), with a new `/dashboard/[port]/voyage-times` page rendering per-visit stacked bars (approach / anchor wait / berth / idle other), median summary cards, and a 50-row drill-down table. Each visit now carries a sibling breakdown that splits arrival → departure into hours spent on **approach**, **anchor wait**, **berth**, and **idle other**, answering the "where did the time actually go?" question that aggregate berth hours alone couldn't. A one-time backfill is populating historical visits. Useful for benchmarking turnaround efficiency, attributing congestion to anchor versus berth bottlenecks, and quantifying loading work versus offshore waiting. * **Overwatch**: Watchlist-scoped vessel-to-vessel near-pass detection for [watchlist](/overwatch/api/watchlist) members. The new detector flags any vessel passing within a configurable distance of a watchlist vessel — including underway encounters that the existing [ship-to-ship transfer detector](/overwatch/api/risk) deliberately filters out (slow speed, outside port zones, latest-position only). Useful for tracking suspicious rendezvous, fleet-against-fleet contact patterns, and dark-fleet associations that don't match the slow-and-loitering STS profile. Backend ships first, with [alert dispatch](/overwatch/api/alerts) wired up later in the week; a UI surface follows in a later release. * **Overwatch**: [Pairwise encounter extraction](/overwatch/methodology/encounter-extraction) — the algorithm that derives vessel-to-vessel CPA, TCPA, range, closing speed, and bearing-rate geometry from raw AIS positions — now runs hourly in production at minute `:07`, with a 30-minute overlap so encounters straddling the hour boundary are captured end-to-end. Stable upsert keys make every re-run idempotent, and a 50,000-pair safety cap aborts runaway windows cleanly. A new backfill driver chunks any historical `since → until` range so a 7-day re-pull completes in roughly 10–20 minutes. Encounter-derived fields on the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs now carry fresher coverage and complete historical fills as a result. * **Overwatch**: Every encounter epoch is now annotated with COLREGS-aligned **rule posteriors** (`p_head_on`, `p_overtaking`, `p_crossing`, summing to 1) and per-vessel **role posteriors** (`give_way_prob`, `stand_on_prob`) derived from epoch geometry alone. Reciprocal-course and bow-aligned gates resolve head-on; parallel-course plus aft-of-beam bearings resolve overtaking; the residual mass goes to crossing, with role assignment by the give-way-on-starboard rule. Clean geometry pushes the matching rule posterior past `0.85`; ambiguous geometry produces a soft mixture instead of a brittle vote. See [Rule and role posterior inference](/overwatch/methodology/encounter-extraction#rule-and-role-posterior-inference). * **Overwatch**: New **Rule 17 deviation flags** on [pairwise encounters](/overwatch/methodology/encounter-extraction). Each encounter now carries per-vessel `max_course_change_deg` and `rule17_deviation` fields. The flag fires when a vessel's mean stand-on probability across the encounter is at least `0.6` *and* its largest single-step course change is `10°` or more — the geometry of a stand-on vessel taking unilateral evasive action that COLREGS Rule 17 only authorizes when the give-way side has clearly failed to keep clear. Useful for surfacing unannounced maneuvers, attributing close-quarters action to the correct party, and cueing forensic review. See [Rule 17 deviation detection](/overwatch/methodology/encounter-extraction#rule-17-deviation-detection). * **Overwatch**: New **Rule 17 handoff timestamp** on [pairwise encounters](/overwatch/methodology/encounter-extraction), building on the deviation flag. Each encounter now records `rule17_handoff_ts` — the exact moment Rule 17(a) "keep course and speed" authority transitions to Rule 17(b)/(c) "may / must take avoiding action" — alongside `rule17_handoff_trigger` indicating whether the transition was driven by **give-way inaction** (give-way vessel hasn't maneuvered while collision risk is high and CPA is closing inside half a nautical mile) or **in extremis** geometry (CPA has collapsed below \~200 m and Rule 17(c) compels stand-on action regardless). Useful for distinguishing premature unnecessary deviation from required avoidance when reviewing close-quarters action. * **Overwatch**: New **vessel density** dashboard at [`/dashboard/density`](/overwatch/getting-started). A daily H3 res-8 density layer aggregates the last 30 days of AIS positions by vessel type, with per-IMO-per-hour bucketing so 10-second-ping vessels can't drown out hourly pingers. Filter by vessel type chip — bulk carrier, tanker, container, etc. — to see where each fleet actually clusters as a viridis-shaded H3 hex map (log-scaled by position count, capped at 5,000 cells per render) alongside a per-type rollup. The layer refreshes daily at 02:00 UTC after yesterday's bucket closes, and the page surfaces the last-refreshed timestamp and freshness status from the underlying ledger so you can tell at a glance whether the view is current. The same data is also exposed at `GET /api/v1/density?type=…&day=YYYY-MM-DD` for programmatic consumers. * **Overwatch**: Course-alteration anomalies now flow into the [vessel risk](/overwatch/api/risk) event stream. A new detector emits a `course_alteration` event whenever an underway vessel deviates by 45° or more from its rolling 6-hour mean heading and is more than 10 km from any port zone, so legitimate maneuvering inside or near a port doesn't generate noise. Each vessel is deduplicated against itself on a 6-hour window, so a single sustained turn produces one event rather than a flood. Useful for surfacing unannounced route changes, evasive maneuvers, and rendezvous course corrections without waiting for a full ship-to-ship pattern to develop. UI surface and alert-rule template follow in a later release. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: This release reported tip-and-cue SAR confirmation of vessel transits through Bab-el-Mandeb, the Strait of Hormuz, the Suez approaches, and Cape Agulhas. The current [Sentinel endpoint](/overwatch/api/sar-coverage) reports scene catalog availability only; it does not detect vessels, confirm a transit, or classify a dark transit. * **Overwatch**: User-defined custom [geofences](/overwatch/api/alerts) on your account. Draw or upload a polygon — a port approach, an EEZ, an ice-edge buffer — optionally scope it to a vessel type or fleet, and Overwatch will record an open event the moment any qualifying vessel enters and close it the moment they leave. The detector runs every minute against a rolling 5-minute window of AIS positions, so a 30-knot vessel covers \~2.5 nm between checks — well under typical user-drawn geofence sizes. Backend ships first; the in-app polygon-draw UI follows in a later release. * **Overwatch**: Watchlist near-pass events now flow into the [alerts dispatch pipeline](/overwatch/api/alerts) alongside dark events, STS events, and OFAC matches. Each alert payload carries the other vessel's IMO and name, the closest-pass distance, and both speeds at the closest fix, with per-watchlist `notify_on` gating so users who only want STS events don't see near-pass traffic. Set `notify_on` to `near_pass` (or `v2v_proximity`) on a [watchlist](/overwatch/api/watchlist) entry to start receiving them. * **Overwatch**: Weekly and monthly [vessel density](/overwatch/api/density) rollups alongside the daily H3 surface, sourced directly from AIS positions rather than summed across the daily matview so unique-vessel counts don't double-count vessels that ping every day. Sixteen rolling weeks and twelve rolling months are now available; both refresh on Mondays and the 1st of each month at 03:00–04:00 UTC after the daily refresh closes. * **Overwatch**: Aircraft tracking is live as a sibling surface to vessel sanctions, targeting the well-documented evasion pattern of sanctioned individuals swapping tail numbers and operating ghost flights. A new aircraft positions feed ingests ADS-B fixes hourly for every airframe in the curated identities list — seed coverage spans Mahan Air (EO 13224), Qeshm Fars Air (IRGC-QF cargo, OFAC 2019), Pouya Air (the rebranded Yas Air, EO 13382 NPWMD), Air Koryo (the DPRK state airline, UN 1718 + OFAC + EU), and Cham Wings / Fly Cham (Syria SDN airframes that survived the July 2025 Syria revocation; the June 2025 rebrand is itself an evasion-tracking signal) — and surfaces a cross-modal lead when a sanctioned aircraft lands within 200 km of a high- or critical-tier dark vessel event. Schema mirrors `ais_positions` for symmetry with the rest of the [risk graph](/overwatch/api/risk). * **Overwatch**: New public per-vessel [`GET /api/v1/ais/{provider}/{imo}/location/latest`](/overwatch/api/vessels) endpoint returns the most recent position for any tracked vessel as a citable URL — no API key required, IP-keyed at 60 requests per minute and 1,000 per day. Pick the provider (`aishub`, `aisstream`, `satellite`, `spire`, or `any`) or let the endpoint pick the freshest fix across all providers. Responses ship a JSON-LD attribution block so journalists, academics, and AI ingestion pipelines can pick up the source claim cleanly. * **Locus**: New free, fully-unlocked [**Fastest-Growing Neighborhoods (Population)** ranking](/locus/mcp-server) sourced directly from U.S. Census ACS 5-year estimates and cited back to [census.gov/programs-surveys/acs](https://www.census.gov/programs-surveys/acs/). Ranks neighborhoods on raw population change between the two most recent ACS 5-year vintages and exposes population-specific columns — *Population Change % (5-year ACS)*, *Population (latest vintage)*, *Population (5 years prior)*, and the ACS vintage used — in full with no preview cap. Tracts with fewer than 1,000 prior residents are filtered out so small-denominator anomalies don't dominate the leaderboard. The existing composite list is now disambiguated as **Fastest-Growing Neighborhoods (Axiom Composite)** and continues to rank on the forward-looking `population_momentum` signal. Use the public list when you need a defensible, third-party-cited answer; use the composite list for Axiom's leading indicator. * **Locus**: New free, fully-unlocked [**Most Building Permits Issued (Last 12 Months)** ranking](/locus/mcp-server) sourced directly from municipal building-permit open data and cross-referenced with the [U.S. Census Building Permits Survey](https://www.census.gov/construction/bps/). Ranks locations by raw permit count over the trailing 12 months across 10 metros (1.2M permits indexed) and exposes permit-specific columns — total permits issued, total declared valuation, and the count of distinct permit types — in full with no preview cap. Every number is verifiable in your city's open-data portal. The list refreshes nightly. * **Layer**: New bulk [contract](/layer/contracts) upload on the **Renewals** page. Drag and drop up to five mixed-format files — text PDFs, scanned PDFs re-saved as images, PNGs, or JPEGs — and Layer extracts vendor, contract value, start date, end date, and renewal terms in parallel using a vision-capable model. Each row shows confidence dots and supports inline editing before you finalize, and any file with missing required fields is flagged as **Needs review** and blocks the batch save until you fill it in. Original files are stored privately so you can re-open the source PDF or image from the contract page later. Single-file upload and the [manual contract](/layer/contracts) entry path are unchanged. * **Layer**: New self-contained **demo mode** for evaluation tenants. Workspaces flagged as demo open with 60+ seeded SaaS apps spanning productivity, dev tools, security and compliance, finance, HR, marketing, sales, and AI — each with 12 months of spend, 18+ contracts spread across the next 12 months of renewals, 12 months of [AI usage](/layer/ai-usage-tracking) records across OpenAI, Anthropic, and Copilot, and a mix of healthy and `needs_reauth` [data source connections](/layer/integrations/overview) so every dashboard, alert, and recommendation has realistic data on first load. A pink banner makes the mode obvious, and a **Reset demo data** action in **Settings** wipes and re-seeds the workspace in a single click. The reset endpoint is hard-gated to demo workspaces, so production tenants can never trigger it. Public per-visitor demo links and ephemeral auto-purge are on the roadmap. * **Layer**: New dedicated **AI Usage** entry in the dashboard sidebar, between **Hardware** and **Renewals**, for tracking LLM spend per employee across OpenAI, Anthropic, Google, and other providers. The page introduces [RouteShift](https://routeshift.io) — the LLM proxy gateway behind Layer's AI cost tracking — with a one-click **Open RouteShift** handoff for managing per-employee keys, smart routing, savings, and live analytics (cache hit rate, p95 latency, error rate, and savings reporting on daily, weekly, or 24-hour windows). Per-employee spend roll-up directly inside Layer is on the roadmap; until then, the existing per-person, department, and provider ROI views remain available via [AI usage tracking](/layer/ai-usage-tracking). * **Layer**: [AI Usage](/layer/ai-usage-tracking) is now a three-tab hub — **Overview**, **Keys**, and **Routing**. **Overview** rolls up per-employee spend with real names instead of opaque IDs. **Keys** is an admin surface that lists every employee with a one-click **Mint** or **Re-mint** action that issues an identity-tagged RouteShift key and shows the plaintext secret in a copy-once modal. **Routing** shows the proxy endpoint, tenant ID, environment-variable status, and a deep link to RouteShift for routing-rule management. Every prompt, completion, and tool call now attributes back to the employee who made it, so per-employee spend rolls up cleanly across BYOK and credit-funded usage. * **Layer**: New **Audit log** entry in the dashboard sidebar for admins, backed by an immutable `audit_events` ledger with 6-year retention. The page renders the 100 most recent events with outcome-coloured pills and is restricted to admin roles. Integration connect and disconnect actions on the [integrations](/layer/integrations/overview) page now write to the ledger automatically, capturing actor, IP, and user-agent. Other surfaces — sync, asset CRUD, and login/logout — wire in over the next few releases. See [Audit log](/layer/audit-log). * **Layer**: New **Sign in with Auth0** option below the email/password form on the [login page](https://app.axiomlayer.io/login). Existing email/password and Google/Microsoft sign-in remain primary; Auth0 runs alongside as an additional Universal Login path during the auth migration. No action required on existing accounts. * **Layer**: Stripe subscription events now flow into a dedicated Layer subscription ledger, so plan changes, renewals, and cancellations originating from [Plans and billing](/layer/billing) reflect in the dashboard within seconds of the Stripe event. Plan tier is derived from the price ID rather than editable subscription metadata, closing a path where a tampered metadata field could upgrade an organization's plan. * **Locus**: Curated [ranking lists](/locus/mcp-server) — *Top Overall*, *Fastest Growing*, *Safest*, *Most Business Active*, *Best for Restaurants*, *Strongest Economies*, *Best Accessibility*, and *Development Hotspots* — now render the columns that drive each list's sort, with the primary metric featured in big-number style next to a sort-direction indicator. Mobile cards mirror the same column order, so the headline metric matches the list's purpose on both layouts. * **Locus**: Each curated [ranking list](/locus/mcp-server) now shows an attribution footer under the table linking to the underlying [methodology](/locus/scoring-conventions), so it's clear at a glance which data source drives the order. Composite-driven lists credit the Axiom Composite Score; future public lists will cite their third-party source directly. * **Locus**: The [rankings index](/locus/mcp-server) is now grouped into two clear sections — **Public Data — Free** for the third-party-cited lists (Census ACS population growth, building permits) and **Axiom Composite — Analyst+** for composite-driven lists. Public lists always render the full top 25 to anyone, including signed-out visitors. Composite-driven lists preview the top 3 rows for free and unlock fully on the Analyst tier ($49/mo), with a clearly badged "Preview (top 3)" CTA on the index and an unlock card after the previewed rows on each list page. The paywall is enforced server-side so locked rows never appear in the HTML source. * **Locus**: The map on [locus.axiomancer.io/explore](https://locus.axiomancer.io/explore) now shows a single national activity heatmap aggregated from the last 90 days of geocoded events, instead of a metro-scoped overlay that saturated inside the active metro. Color stops are retuned for the long-tail count distribution so dense metros read as the hottest spots without blowing out the rest. The explorer sidebar also gained an explicit **Back to Dashboard** link. * **Locus**: The signed-in [dashboard](https://locus.axiomancer.io/dashboard) now opens with a national activity mini-map between the page header and the stat cards, rendering the same 90-day heatmap as the [explorer](https://locus.axiomancer.io/explore) so the dashboard preview and the deep-dive read as one continuous surface. Click anywhere on the map to land in the explorer at that location with the score panel ready, and use the **Open Explorer** button in the top-right for the full-map handoff. Palette and weight stops match the explorer exactly. * **Locus**: The [explorer](https://locus.axiomancer.io/explore) now leads with intelligence rather than geometry. The map narrows to about a quarter of the viewport on large screens, and a new **Intelligence Rail** fills the rest with live alerts, top movers, monitored locations, and a metro-pulse snapshot — sourced from the same data that powers the signed-in dashboard. The cell-level score breakdown still lives in the left sidebar when you click a hex. A new mode toggle flips between the integrated view and the previous full-bleed map; append `?mode=fullscreen` to the URL to land directly in the original layout. Below the large breakpoint, the rail is hidden and the map fills the page so mobile and tablet keep a map-first layout. * **Locus**: The Intelligence Rail on the [explorer](https://locus.axiomancer.io/explore) is now cell-aware. When you click a hex, a Selected-cell panel pins to the top of the rail with the cell's composite score, a 90-day score sparkline (trend-colored — emerald rising, red declining, dim flat, dashed when the underlying history is a synthetic fallback), and a signal contribution waterfall that ranks the eight signal groups by score with tier-colored bars so the strongest signals lead. Monitored locations filter to the active metro with explicit empty-state copy ("No monitored locations in SF yet"), and the rail header subtitle flips between *Live signal feed for the current map* and *Cell selected · \{METRO} context* so the mode is legible at a glance. A metro key-stats strip — composite average, GDP YoY, top-scoring signal — sits above the rail. The full sub-signal breakdown still lives in the sidebar's score panel. * **Locus**: Each row in the cell-detail signal contribution waterfall now click-throughs to its [signal group](/locus/scoring-conventions) detail page — business vitality, population momentum, demographics, economic strength, development pipeline, accessibility, safety & environment, and amenity demand — so you can jump from "this cell scores 78 on development pipeline" straight into the sub-signals and methodology behind that group in one click. Legacy signal labels render without a link. * **Locus**: The Intelligence Rail now includes a **Peer Metros** comparison band that plots the active metro's composite score against its three closest-by-composite peers as horizontal bars on the absolute 0–100 scale, so widths are directly comparable. Each peer row links straight to that metro's pulse page, making a hop into deeper context one click away. * **Locus**: The Intelligence Rail now includes a **Safety Tier Mix** stacked-bar that shows how the active metro's scored cells distribute across five safety tiers — Prime, Strong, Solid, Watch, and Elevated — so you can answer "is this metro mostly safe, or mostly elevated?" without leaving the page. The same component is wired to render distributions for any of the eight signal groups in future updates. * **Locus**: The Intelligence Rail now includes a **12-month permit trend** chart that plots the active metro's monthly building-permit volume as a small bar series so you can read the trajectory at a glance — accelerating, plateauing, or rolling over — without leaving the [explorer](https://locus.axiomancer.io/explore). Sourced from the same municipal feeds that power the [Most Building Permits Issued ranking](/locus/mcp-server). * **Locus**: New free public [**Most Appreciated Real Estate (12-month price growth)** ranking](/locus/mcp-server) sourced directly from the [FHFA House Price Index](https://www.fhfa.gov/data/hpi). Ranks metros by trailing-12-month repeat-sales appreciation with the FHFA HPI backfill behind it, full top 25 visible to anyone with explicit citation in the attribution footer. * **Locus**: New free public [**Highest Mortgage Activity (Last 12 Months)** ranking](/locus/mcp-server) sourced from public [HMDA](https://www.consumerfinance.gov/data-research/hmda/) loan-application data. Ranks metros by trailing-12-month mortgage origination volume with full top 25 unlocked. * **Locus**: New free public [**Lowest Crime Rate** ranking](/locus/mcp-server) sourced directly from FBI UCR / NIBRS and municipal open-data crime feeds. Ranks neighborhoods by part-1 incidents per 1,000 residents over the trailing 12 months with the source cited inline. * **Locus**: New free public [**Best Public Schools** ranking](/locus/mcp-server) sourced from the [NCES Common Core of Data](https://nces.ed.gov/ccd/). Ranks neighborhoods by aggregate school-quality score across nearby public schools, with the underlying NCES record visible per row. * **Locus**: New free public [**Most Parks** ranking](/locus/mcp-server) ranks neighborhoods by per-cell park count and total park acreage from the curated POI catalog. Useful for residential, retail, and amenity-driven site selection. * **Locus**: Two new Analyst+ momentum rankings — [**Fastest-Rising Cells**](/locus/mcp-server) and [**Fastest-Falling Cells**](/locus/mcp-server) — surface the cells whose Axiom Composite Score moved the most over the trailing 7, 30, and 90 days. Where the existing leaderboards rank by current level, these rank by *change*, so they answer "where is something quietly happening right now?" ahead of the next quarterly recompute. Each row carries the latest composite, the composite at each lookback window, the signed delta, and the snapshot date so you can verify the move directly. Refreshed nightly at 04:15 UTC after the daily score-history rollover. * **Locus**: New **Council Activity** card on every [metro pulse page](https://locus.axiomancer.io/pulse) showing the trailing-90-day count of high-signal council meetings, rezonings approved, new-construction approvals, housing units mentioned, dollar amounts, and the most recent meeting date — sourced from extracted council and planning-commission decisions in the [civic intelligence dataset](/codex/schemas/civic-intelligence). Live for San Francisco, Chicago, and Houston this week, with additional metros rolling in as extraction coverage expands. The card hides itself when no extracted decisions are available so coverage gaps stay clean. * **Locus**: Four new **live public stats** on every [metro pulse hero](https://locus.axiomancer.io/pulse) — *Population Δ*, *Home Price Δ*, *Median Household Income*, and *Median Gross Rent* — sourced directly from Census ACS B19013 and B25064 and the FHFA HPI, replacing static placeholder copy. Eight verifiable public numbers now lead every metro page with explicit BEA, BLS, Census ACS, and FHFA citations alongside. * **Locus**: The 8-signal grid and metro composite score on the [metro pulse pages](https://locus.axiomancer.io/pulse) are now teaser+blur for free visitors with an Analyst+ unlock card, while the public stats hero (population, home prices, income, rent) and #1 top-neighborhood remain free. The split mirrors the [rankings index](/locus/mcp-server) — public, third-party-cited numbers stay free; Axiom's composite scoring unlocks at the $49/mo Analyst tier. * **Locus**: New **Maritime → CRE port-risk** propagation surfaces a port-congestion warning on cell detail panels when a Locus metro's primary or secondary port is showing elevated wait times in [Overwatch](/overwatch/api/disruptions). Twenty-two Locus metros are now mapped to the major US ports in their economic catchment by trucking corridor (e.g. Phoenix → Los Angeles / Long Beach via I-10), with risk levels of *watch*, *elevated*, or *severe* derived from p90 wait, median wait, and trend. The badge hides itself when seas are calm. * **Locus**: Top movers on the [signed-in dashboard](https://locus.axiomancer.io/dashboard) are now split into two side-by-side panels — **Risers** and **Decliners** — instead of a single mixed list, so positive and negative momentum are equally legible at a glance. Same data, two columns. * **Locus**: Refreshed [locus.axiomancer.io](https://locus.axiomancer.io) home page with corrected platform stats (12M+ temporal events, up from a stale 3M+ figure) and a new **Verify every number** showcase between the customers section and the CTA. The showcase leads with the four free public-data rankings (FHFA HPI, HMDA, building permits, crime), each with its public source and citation URL visible inline. * **Locus**: New **Compare plans** strip on the [free Location Report page](https://locus.axiomancer.io/free-report) summarizes what each tier unlocks side-by-side — *Free now* (one report), *Analyst at $49/mo* (50 cells, portfolio tracking, CSV export), and *Pro at $199/mo* (500 cells, custom formulas, full API) — with a **See full pricing →** link straight to [locus.axiomancer.io/pricing](https://locus.axiomancer.io/pricing). Visitors can now read the upgrade path the moment they request a free report, instead of clicking through to find it. * **Locus**: Three new civic-intelligence collectors — meeting **audio** transcription, **zoning board of appeals (ZBA) PDF** extraction, and **court dockets** — feed the [civic intelligence dataset](/codex/schemas/civic-intelligence) and downstream Council Activity cards. Loaders for `business_licenses`, `court_dockets`, and `zba_decisions` are unblocked end-to-end. * **Locus**: City council collection now defaults to **Legistar HTML scraping** instead of the JSON API, so metros where the Legistar JSON surface is incomplete (most of them) ingest the full set of meeting items, sponsors, and dispositions out of the box. Same data path that powers [council decisions](/codex/schemas/civic-intelligence) on Codex. * **Locus**: The Nearby POIs list in the [explorer](https://locus.axiomancer.io/explore) sidebar is now collapsed into an accordion by default, so the at-a-glance Nearby summary badges and Crime Safety indicator stay in view without the long POI list pushing them off-screen. Expand the accordion to see the full list. * **Locus**: Named [portfolios](/locus/api/portfolios) with bulk CSV upload — drop a CSV of `lat,lng` or `address` rows (geocoded against U.S. Census TIGER, 500-row cap), and a portfolio-level composite (equal-weight mean of member cells' [Axiom Composite Scores](/locus/scoring-conventions)) sits at the top of each detail page. A one-click **Refresh scores** action repulls the latest [cell scores](/locus/scoring-conventions) for every member in a single call * **Locus**: New [`/business-licenses`](/locus/business-licenses) dashboard with record-by-record search across the normalized business-license catalog covering 15 U.S. metros. Filter by metro, address, NAICS prefix, and pioneer-tier classification. **Export CSV** for the visible page * **Locus**: New [`/zba-decisions`](/locus/zba-decisions) dashboard makes Zoning Board of Appeals decisions searchable across **Chicago**, **Boston**, **NYC**, and **Philadelphia**. Filter by jurisdiction, case number, address, outcome, variance type, and date range. **Export CSV** for the visible page * **Locus**: **Saved searches** and a per-row **+ Portfolio** action on the Locus [discover](https://app.axiomlocus.io/discover) surface. Persist any active filter set as a named saved search and re-open it from a new dashboard panel * **Locus**: New **Flood Loss History** sub-signal feeds the [safety & environment](/locus/scoring-conventions) score, sourced from 677K+ FEMA NFIP flood-insurance claims aggregated to each cell's nearest zip * **Locus**: New **Complaint Trend YoY** sub-signal in [safety & environment](/locus/scoring-conventions) — the year-over-year delta on a cell's trailing 30-day 311 complaint density, treated as a Pioneer Stage 1 signal * **Layer**: [axiomlayer.io](https://axiomlayer.io) now renders branded link previews when shared on Slack, Twitter, LinkedIn, or any embed-friendly surface. Previously, shares had no card at all. The new image uses the refreshed pink and indigo brand palette and highlights the free [shadow IT scan](/layer/integrations/google-workspace). * **Codex**: [axiomcodex.io](https://axiomcodex.io) now ships branded OpenGraph preview cards and a `summary_large_image` Twitter card, so links unfurl with a full-bleed gold-on-black preview instead of the old small thumbnail. * **Platform**: The [Axiomancer Labs landing page](https://axiomancer.io) now ships a 1200×630 OpenGraph preview card in the cross-product cyan-and-gold palette and uses the larger `summary_large_image` Twitter card, so links to the parent site unfurl as full-bleed branded previews on Slack, X, LinkedIn, and any embed-friendly surface. * **Codex**: A `robots.txt` and `sitemap.xml` are now served at the site root, enumerating the [standards](/codex/normalization-standard) overview and every standard page so search engines can index them without relying on nav-link discovery. * **Codex**: [axiomcodex.io](https://axiomcodex.io) now emits structured data (`SoftwareApplication` JSON-LD) on the homepage, including pricing tiers and organization details, so Google can surface rich pricing and category hints in search results and AI overviews. * **Layer**: [axiomlayer.io](https://axiomlayer.io) now serves a `robots.txt` and `sitemap.xml` covering the public marketing surface — home, [free shadow IT scan](/layer/integrations/google-workspace), signup, login, privacy, and terms — so search engines can discover and index the site without relying on link traversal. Authenticated dashboard and onboarding routes are explicitly disallowed. * **Platform**: The [Axiomancer Labs landing page](https://axiomancer.io) now serves a `robots.txt` and `sitemap.xml` at the site root so search engines can discover the homepage directly. The internal `/api` surface is explicitly disallowed. * **Platform**: [axiomancer.io](https://axiomancer.io) now embeds Organization structured data (JSON-LD) on every route with `sameAs` links to all four product domains — [axiomlayer.io](https://axiomlayer.io), [axiomoverwatch.io](https://axiomoverwatch.io), [locus.axiomancer.io](https://locus.axiomancer.io), and [axiomcodex.io](https://axiomcodex.io) — so Google can build the Axiomancer Labs knowledge-graph relationship between the parent brand and its sub-products. * **Platform**: [RouteShift](/routeshift) is now a first-class product alongside Layer, Overwatch, Locus, and Codex in the cross-product navigation bar at the top of every Axiom site, so you can switch into the LLM proxy gateway from anywhere in the platform with one click. The bar's emerald RouteShift mark matches the brand palette already used on the [Layer AI Usage hub](/layer/ai-usage-tracking) handoff and on [routeshift.io](https://routeshift.io). * **Platform**: New **RouteShift** card on the [Axiomancer Labs](https://axiomancer.io) Products catalog, alongside Overwatch and Locus. The card surfaces RouteShift's headline stats — 12 supported providers and 3% of measured savings — and links straight to [routeshift.io](https://routeshift.io) for sign-up. ### Updates [#updates] * **Overwatch**: Panning the [live map](/overwatch/getting-started) to a new region of the globe is now instant — the map loads the full global vessel layer once on first paint and renders every subsequent pan from data already on the client, matching the always-on-globe feel of VesselFinder and MarineTraffic. Positions still refresh every five minutes. * **Overwatch**: Vessel markers on the [live map](/overwatch) now use elongated, bow-forward triangles that match the industry-standard silhouette on VesselFinder and MarineTraffic, so heading direction is easier to read at a glance. Vessels are also more visible at world and regional zoom levels. * **Overwatch**: All 40+ [dashboard](/overwatch/getting-started) sub-pages and shared chrome — sidebar, mobile nav, global search, and port selector — now share the obsidian-and-amber palette of the new terminal, so jumping from the terminal to any `/dashboard/*` page no longer flips colors. Primary buttons, status badges, and divider/ring accents across every sub-route were tuned in a follow-up pass so they read clearly against the dark background instead of merging into it. The sidebar header also gained a **← Term** pill to jump back to the terminal in one click. * **Overwatch**: The default homepage hero map has moved from the Bosphorus Strait to the Port of Long Beach, giving you an immediate view of one of the busiest container ports in the Western Hemisphere when you first land on Overwatch. * **Overwatch**: Refreshed live platform counts on [axiomoverwatch.io](https://axiomoverwatch.io) and the [intelligence](https://axiomoverwatch.io/intelligence) and [platform](https://axiomoverwatch.io/platform) marketing pages — 31.5M AIS positions (up from 7.15M), 41,000+ tracked vessels (up from 18,600), 369K port events, and 26K dark events — pulled directly from production rather than the previously stale figures. * **Overwatch**: Approximately 16,000 historical vessel visits that were missing hydrostatic [cargo estimates](/overwatch/methodology/cargo-validation) have been retroactively processed, so previously empty cargo fields on departed vessels now carry tonnage estimates calculated using the same methodology as live arrivals. No action is required on your part. * **Overwatch**: Equasis [vessel enrichment](/overwatch/api/vessels) now surfaces ISM Manager, Commercial Manager, and Technical Manager as their own fields and emits a distinct relation per role on the vessel relationship graph. The legacy `ship_manager` field keeps its ISM-fallback behavior so existing consumers see no change. When ISM and ship manager are the same company, the graph still records a single edge per relation and target. * **Overwatch**: The cross-product navigation bar now appears consistently on every page — including intelligence, blog, pricing, and dashboard sub-pages — so you can switch between Layer, Overwatch, [Locus](https://locus.axiomancer.io), and [Codex](https://axiomcodex.io) from anywhere. * **Platform**: [RouteShift](https://routeshift.io) is now the fifth product in the cross-product navigation bar across every Axiomancer site, alongside Layer, Overwatch, Locus, and Codex. Jump straight to the LLM proxy gateway — or its [docs](/routeshift/getting-started) — from any Axiomancer surface in one click. * **Platform**: Faster first paint and Largest Contentful Paint on the [Axiomancer Labs landing page](https://axiomancer.io). The hero Mux video player now renders server-side so the browser can request the player chunk and manifest immediately instead of waiting for hydration, two unused display fonts that were generating preload tags competing with the Mux preconnect have been dropped, and the Mixpanel (\~70 KB) and Intercom (\~90 KB) launchers are now deferred behind dynamic imports and `requestIdleCallback` rather than running on the critical path. The PostHog analytics SDK is also deferred until the browser is idle, dropping \~244 ms of session-recorder work out of the initial bundle and shaving roughly 800 ms off PostHog bootup time as measured by Lighthouse. Page-view tracking is unchanged. Social-media unfurls also got a small win — the OpenGraph image now caches its Inter font fetch so each scrape no longer triggers a cold Google Fonts hop. * **Locus**: Faster Largest Contentful Paint on the [locus.axiomancer.io](https://locus.axiomancer.io) home page. The hero video poster is now preloaded at high priority from the initial document, so it appears earlier instead of waiting for the player to mount, and is requested from a CDN-warm preset size — dropping roughly 1.3 MB from the home page payload at the same visual quality and avoiding the multi-second origin-resize stall first-time visitors were hitting. * **Overwatch**: Faster hero video startup on [axiomoverwatch.io](https://axiomoverwatch.io). The browser now warms TLS connections to the Mux streaming origins while the rest of the page is still parsing, so the homepage hero begins playback noticeably sooner on a cold first visit. * **Overwatch**: Sharper homepage first paint on [axiomoverwatch.io](https://axiomoverwatch.io). The hero thumbnail — the largest element on first load — is now declared as a preload hint in the initial document and reused as the video player's poster, so it's discovered in parallel with the rest of the page and only fetched once. * **Overwatch**: Faster catch-up on AIS [downsampling](/overwatch/data-retention) and a cleaner long-term archive path. Each downsample run now processes up to five days per tier instead of one, so any backlog drains in days rather than weeks while steady-state runs still touch only the most recent day. Positions older than 90 days are now served from the cold archive instead of the live database, so the [retention windows](/overwatch/data-retention#retention-windows) on the live database top out at 90 days. Archived positions remain available at full resolution on request — see [Archive storage](/overwatch/data-retention#archive-storage). * **Overwatch**: Satellite [AIS coverage](/overwatch/ais-coverage) polling is back on its hourly cadence after a temporary pause to keep credit usage from leaking on a stale configuration. The pipeline now fails fast with an explicit error and a logged ingestion record when its API key is missing, so any future configuration gap is loud and catchable instead of silently burning lookups. Per-run lookup caps are unchanged. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: Terrestrial [AIS coverage](/overwatch/ais-coverage) widened to the chokepoint corridors that were intended to feed SAR confirmation — Bab-el-Mandeb, the Strait of Hormuz, the Suez approaches, and Cape Agulhas. The current supported workflow uses AIS evidence; Sentinel catalog coverage does not enter the confirmation path. * **Overwatch**: Per-vessel ETA confidence bands on the [forecasts API](/overwatch/api/forecasts) are now calibrated against the actual transit-speed distribution observed for each vessel class, instead of a flat ±20% / ±30% multiplier. The new model derives p10/p25/p50/p75/p90 effective transit speeds from real port-to-port voyage history, with a minimum of five sample voyages per class and floor/ceiling guards on degenerate single-sample classes. Bulk carriers, container ships, and tankers now carry tighter, class-appropriate envelopes; forecasts using the new model are tagged `forecast_method = 'great_circle_v2_class_calibrated'` so dual-write coverage can be backtested against the prior heuristic. * **Overwatch**: All 41 [FRED](https://fred.stlouisfed.org/) economic series now ingest cleanly. The first production run surfaced two retired series codes — the trade-balance series and a paperboard-container industrial-production series — which have been swapped for their current FRED equivalents (`AITGCBS` and `IPN32221S`). The semantic intent of each replacement (trade balance, freight proxy) is unchanged. * **Locus**: Free Location Report requests on [locus.axiomancer.io](https://locus.axiomancer.io) now require a Cloudflare Turnstile CAPTCHA and email confirmation by the recipient before the report is generated and sent, so the request form can no longer be used to mail unsolicited reports to non-consenting addresses. The recipient receives a confirmation link with a 24-hour expiry and lands on a new **Report confirmed** acknowledgment page after clicking through. Per-IP and per-recipient daily rate limits add a further backstop. * **Locus**: The `developmentPipeline` signal group on `/api/score` now incorporates a new **Permit Scope Quality** sub-score (`source: "AXL-108"`, weight 0.10) that weights every recent permit by its LLM-extracted `scope_type` (new construction, addition, demolition, renovation, repair) and `estimated_cost_tier`, so cells dominated by genuine new construction separate cleanly from cells where permits mostly reflect maintenance churn. Composite and group scores remain on the same 0–100 scale; cells without LLM-annotated permits see `AXL-108` listed under the group's `sourcesMissing` instead. See [Development pipeline sub-scores](/locus/scoring-conventions#development-pipeline-sub-scores). * **Locus**: Each row in the cell-detail signal contribution waterfall on the [Explorer](https://locus.axiomancer.io/explore) score panel is now click-through. Selecting any of the eight canonical [signal groups](/locus/scoring-conventions) — *Business Vitality*, *Population Momentum*, *Demographics*, *Economic Strength*, *Development Pipeline*, *Accessibility*, *Safety & Environment*, or *Amenity Demand* — jumps you straight to the corresponding `/signals/[group]` detail page so you can dig into how that signal is computed without leaving the Explorer. Legacy or composite labels with no detail page render as plain text. * **Locus**: The cell-detail signal contribution waterfall now carries per-signal **freshness chips** alongside an aggregate "refreshed *X* ago" indicator on the section header, so a stale score is impossible to miss at a glance. Chips are color-coded by SLA — dim under 72 hours, amber 72–168 hours, red beyond a week — and hovering shows the absolute refresh timestamp. * **Locus**: The default `general` [scoring profile](/locus/scoring-conventions#scoring-profiles) on `/api/score` has been rebalanced to align signal weights with peer-reviewed CRE price-correlation literature. **developmentPipeline** moves from 0.12 to 0.20, **economicStrength** from 0.15 to 0.20, and **accessibility** from 0.10 to 0.12, offset by trims to **businessVitality** (0.20 → 0.15), **populationMomentum** (0.15 → 0.10), **demographics** (0.12 → 0.10), and **amenityDemand** (0.08 → 0.05). Use-case profiles (`qsr`, `office`, `industrial`, `retail`, `data_center`, `self_storage`) are unchanged. Pin to the previous behavior with `profile_version` if you need replicable historical scores. * **Locus**: Cell scoring now supports **per-metro H3 resolution** overrides. Ten low-density, large-parcel metros — Phoenix, Houston, Las Vegas, Dallas, San Antonio, Nashville, Jacksonville, Oklahoma City, El Paso, and Fort Worth — are now scored at H3 r7 (\~5.16 km²) instead of the default r8 (\~0.74 km²) so each cell carries enough samples to be statistically meaningful. Every row in `cell_scores` is tagged with the resolution it was computed at via `resolution_variant` — filter or group on it if you query across metros. See [Per-metro resolution overrides](/locus/scoring-conventions#per-metro-resolution-overrides). * **Locus**: The [`/api/score/batch`](/locus/api/overview) endpoint is now rate-limited and validates every H3 index in the request body as 15-character lowercase hex before hitting the database, bringing it in line with [`/api/cells`](/locus/api/overview), [`/api/pois`](/locus/api/overview), and the rest of the metered surface. Responses now include `X-RateLimit-Remaining` so clients can pace themselves; the existing 200-cell cap and CDN cache for repeat H3 sets are unchanged. * **Locus**: API key daily request quotas now read from the canonical [plans table](/locus/api/overview) instead of a stale `{free, pro, team}` lookup, so Analyst, Enterprise, and Supply Chain Risk subscribers get their full quota on `/api/keys` instead of silently falling through to the 10-request-per-day Free ceiling. * **Locus**: Faster [`/api/score`](/locus/api/overview) responses. The supplemental data fetch — covering \~18 additional queries that don't depend on the core scoring inputs — now runs concurrently with the seven core scoring RPCs instead of waiting for them to finish, removing one full round-trip from every scoring call. Median latency drops by roughly 100–200 ms with no behavior change on the response payload. * **Locus**: New scoring-research surfaces document Locus's robustness to the [Modifiable Areal Unit Problem (MAUP)](/locus/scoring-conventions) — the well-known sensitivity of spatial statistics to grid choice. The platform now ships an H3 resolution ensemble (r6/r7/r8/r9), a grid-jitter spatial-robustness check, signal-distribution sensitivity (S-MAUP), MAUP decision sensitivity for ranked decisions, and a *consensus core* / *ambiguity shell* classification per cell so you can tell at a glance which scores are robust across grid choices. A metro-velocity multiplier on temporal decay also lets fast-moving metros decay older signals faster than slow movers. * **Layer**: Refreshed link previews and tab titles on [axiomlayer.io](https://axiomlayer.io). The Twitter and OpenGraph metadata now leads with Layer's current Lifecycle Operations positioning instead of the older "IT Asset Management" framing, so shares unfurl with up-to-date copy. * **Layer**: Faster icon rendering across the dashboard. The Iconify icon CDN is now warmed during the initial page load, so connector tiles, sidebar icons, and integration logos paint sooner on first visit. * **Codex**: Faster Largest Contentful Paint on the [axiomcodex.io](https://axiomcodex.io) home page. The hero Mux video player is now lazy-loaded so the poster image can paint before the \~200 KB player chunk arrives, the Mixpanel (\~70 KB) and Intercom (\~90 KB) launchers are deferred behind dynamic imports and `requestIdleCallback`, and the browser warms TLS connections to the Mux streaming origins while the page is still parsing. The hero poster is also preloaded at high priority directly from the initial document, so the largest visible element on first load is discoverable in parallel with the rest of the page instead of waiting for the player to mount. * **Overwatch**: Faster [vessel detail page](/overwatch/api/vessels) loads. The page was firing a dozen IMO-keyed lookups one after the other — visits, dark events, ship-to-ship transfers, loitering, identity history, P\&I coverage, sanctions, destination reliability, draft mismatches, voyage earnings, and positions — even though only related-anomaly enrichment depended on visits. The independent queries now run in parallel, cutting roughly 300–700 ms of round-trip time off every vessel detail load. * **Overwatch**: Faster vessel context popups on the [live map](/overwatch/getting-started). The live weather fetch and the local port-weather fallback now run concurrently instead of the fallback waiting for the live fetch to finish or time out, so a slow upstream response no longer pushes popup latency past 4.5 s. The Amplitude analytics SDK is also now deferred behind `requestIdleCallback`, moving \~150–200 KB off the critical hydration path so it doesn't compete with map WebGL initialization. Tracking is unchanged. * **Overwatch**: Smaller bundles on every page that loads the dynamic [live map](/overwatch/getting-started) wrapper. The Mapbox GL stylesheet was being pulled in twice — once by the underlying map component and again by the wrapper — adding roughly 15 KB of redundant CSS to every parent bundle that imported the wrapper, including routes that never actually rendered a map. The duplicate import has been removed; the styles still load with the map itself, so map rendering is unchanged. * **Overwatch**: Stripe checkout from the [pricing page](https://axiomoverwatch.io/pricing) now accepts promotion codes, matching Layer, Locus, and Codex. Apply a valid coupon directly in the Stripe-hosted checkout — no support handoff needed. * **Locus**: Faster cold-start latency on the [`/api/export`](/locus/api/overview) endpoint. A previously-dynamic plan-feature import is now resolved at module load time, so the first export request after a cold invocation no longer waits on a serialized module init alongside the auth round-trip. Steady-state latency is unchanged. * **Locus**: New `saved=true` filter on [`/api/export`](/locus/api/overview) restricts the response to the cells you have saved as monitored locations, so portfolio-level CSV and JSON pulls are now a single call instead of an export-then-filter dance. Combine with `format=csv` or an existing `metro=` filter to scope the output further; an empty saved set short-circuits to a clean empty response without a full-table scan. The endpoint remains gated to plans with the `bulk_export` feature. * **Layer**: Faster marketing hero on [axiomlayer.io](https://axiomlayer.io). Hero copy and headline now render server-side with a CSS-driven entrance animation, so the largest above-the-fold text paints immediately on first load instead of waiting on client hydration. * **Layer**: Cost-rollup responses on the dashboard now set `Cache-Control: private, no-store`, so per-employee, hardware, and AI cost roll-ups can never be served from a CDN cache to the wrong tenant. Public marketing endpoints are unchanged. * **Layer**: Faster [dashboard](https://app.axiomlayer.io/dashboard) first paint — roughly 450–1200 ms quicker. The hardware costs, employee costs, and security discovery panels previously fetched in three sequential round-trips before rendering; those calls now run in parallel, so total time-to-first-byte is bounded by the slowest single fetch instead of the sum. The [assets](/layer) listing page also fetches a narrower column set tailored to the table view, avoiding pulling raw payload and wide metadata blobs over the wire on large tenants. * **Layer**: Marketing copy now consistently describes the [integration catalog](/layer/integrations/overview) as **40+ integrations**. The hero, integrations wall, FAQ answer on the marketing route, the landing-page mirror copy, and the Starter pricing card had been overstating the count at 80+; the catalog itself is unchanged — only the marketing claim was corrected. * **Layer**: The dashboard sidebar logo is now visually aligned with the AxiomBar brand mark, so the in-product chrome reads as one continuous surface from the cross-product bar through the sidebar header on every page. ### Fixes [#fixes] * **Overwatch**: Hardened the [v1 API](/overwatch/api/overview) against database-error leakage. All 500 responses now return a generic `Internal server error` message instead of forwarding the underlying Supabase error text, which previously surfaced internal column names, constraint identifiers, and occasional row fragments to API clients. Real error detail is still captured server-side for debugging. * **Overwatch**: Closed a tier-escalation path on the [v1 API](/overwatch/api/overview). Internal admin tier (100k req/day, exports, positions, webhooks) is now strictly gated on the `X-Internal-Auth` shared secret. The previous fallback that granted admin tier when the request `Origin` or `Referer` host matched the API host has been removed, since both headers can be spoofed from non-browser callers. * **Overwatch**: Added a Content-Security-Policy header across the entire stack and lifted HSTS to a 2-year `max-age` with `preload`, matching the platform-wide baseline. The CSP is tuned for the actual provider stack — analytics, Mux Player, Intercom, and Mapbox — and includes `frame-ancestors 'none'` for clickjacking defense even when `X-Frame-Options` is dropped by intermediaries. * **Overwatch**: [Alerts](/overwatch/api/alerts) queries now anchor on the API key owner at the query layer in addition to row-level security, so alerts can never be exposed to the wrong tenant if the auth surface shifts in a future change. No behavior change for valid callers. * **Overwatch**: Fixed a [berth utilization](/overwatch/api/berth) regression where every berth zone in a port returned the same port-wide aggregates for occupancy %, vessels served, and total tons handled. Per-zone occupancy is now computed correctly via the spatial join the schema already supports, so `/api/v1/berth-utilization` and `/api/v1/berth-utilization/weekly` return distinct numbers per zone. * **Overwatch**: Stripe checkout from [pricing](https://axiomoverwatch.io/pricing) now redirects to the production apex (`axiomoverwatch.io`) when the app URL env var is unset, instead of falling back to a personal preview deployment URL. Customers can no longer be sent off-domain after completing checkout. * **Overwatch, Locus**: Restored end-to-end plan upgrades from Stripe checkout. The webhook handler claims an idempotency record before applying each Stripe event, but the underlying table was missing from the shared Overwatch/Locus database, so every claim insert silently failed and the handler short-circuited as a duplicate — leaving paying customers on the free plan after a successful checkout. The table is now in place and captured in source migrations, so subscription, invoice, and customer events apply on first delivery and plan tiers update within seconds. Affected customers have already been reconciled. * **Overwatch**: The [`robots.txt`](https://axiomoverwatch.io/robots.txt) sitemap URL now points at the apex domain and the unlinked PTKG demo page is explicitly disallowed from crawler indexing. * **Overwatch**: Vessel context cache no longer reuses tier-gated data across users — each request is now keyed by the requesting account's tier, so signed-in views and anonymous views read from separate cache entries. * **Locus**: Resolved a crash on first page load that surfaced as a generic "Application error" screen. Analytics initialization was running out of order; the fix sequences it correctly so the app loads cleanly on first visit. No action is required on your part. * **Locus**: [Walkability scoring](/locus/api/overview) now counts pedestrian infrastructure by category — footways, crossings, intersections, and sidewalks each tallied separately from OpenStreetMap — instead of taking a single union-wide total and splitting it 40/20/20/20 across the four categories. A cell with 100 footways and zero crossings was previously credited with 20 phantom crossings; per-cell walkability scores now reflect what's actually on the ground. * **Locus**: Plan lookups no longer silently downgrade paying users to Free during a transient outage of the subscriptions table. The auth helper still fails open to Free so feature gates stay responsive, but non-recoverable errors are now logged server-side so subscriptions outages are observable instead of quietly capping paying users at the Free quota. * **Locus**: [`/api/score`](/locus/api/overview) responses for paid tiers now set `Cache-Control: private, no-store`, so a CDN can't serve a Team-tier response — including raw signal values, weights, and provenance — back to a Free-tier user that hits the same lat/lng. Free-tier responses are still cached as before. * **Locus**: The [`/api/keys`](/locus/api/overview) and [`/api/export`](/locus/api/overview) endpoints no longer return raw database error text — including table, column, and constraint names — to API clients on 500 responses. Real error detail is still captured server-side for debugging; clients now receive a generic message. * **Locus**: Hardened budget caps on the pipelines that refresh [POI inventory](/locus/scoring-conventions#data-freshness) for Locus scoring, so concurrent jobs racing on the same counter can no longer push usage past each upstream provider's free-tier ceiling. Per-key Google Places usage now caps with a small safety margin, the global weekly collection budget caps below the combined ceiling, and Yelp now has an explicit monthly cap under its free-tier limit. POI freshness on the [data freshness table](/locus/scoring-conventions#data-freshness) is unchanged — the weekly refresh still completes well within the new budgets. * **Locus**: More accurate neighborhood names on cell [enrichment](/locus/api/enrichment), [scoring](/locus/scoring-conventions), and [location lookups](/locus/api/location-data). Neighborhoods now resolve to the names you'd recognize from Google Maps — *SoHo*, *Williamsburg*, *Mission District* — instead of the administrative subdivisions the previous source returned (NYC Community Boards, township and city names elsewhere). Curated polygons are preferred, with OpenStreetMap and Census fallbacks for areas without curated coverage. Rows that previously returned a Community District name have been cleared and a backfill is populating full coverage across all 22 supported metros. * **Codex**: In-app support chat fonts now load cleanly on [axiomcodex.io](https://axiomcodex.io). The Intercom messenger pulls its typeface from a separate font subdomain that was not on the allowlist, generating browser console errors on every page view. Console is now clean and the messenger renders with its intended typography. * **Overwatch**: More resilient ingestion of cultural amenity data from OpenStreetMap. Records with freeform `start_date` values like `"1870"` or `"c. 1900"` no longer fail to load — the ingestion job validates the date and falls back to ingestion time when the value can't be parsed, so the long tail of historical sites flows in cleanly. Coverage on the [envelope dashboard](/codex/envelope-coverage) is unchanged. * **Overwatch**: Brazilian ANTAQ vessel-call ingestion no longer silently strands existing rows without cargo tonnage. Three concurrent issues — an upsert path that ignored later updates instead of patching them, a swallowed Carga-archive fetch failure that hid the missing-cargo cause from operators, and a scoping bug in the temporal-edge emission that threw whenever bulk arrivals were processed — were all fixed in one pass. Cargo tonnage now flows into the [cargo validation](/overwatch/methodology/cargo-validation) pipeline as soon as the upstream archive is reachable, and any future fetch failure surfaces on the [status page](/overwatch/status-page) instead of disappearing into a console warning. * **Overwatch**: Vessel visit completion is reliable again. A schema mismatch was silently rejecting the closing update on each visit, leaving status stuck on the prior value and [hydrostatic cargo confidence](/overwatch/methodology/cargo-validation) blank — the closing write now succeeds, so visits transition to `departed` cleanly and confidence is populated end-to-end. * **Overwatch**: Stale-data-source alerts on the [status page](/overwatch/status-page) now clear automatically as soon as the source recovers, including for slower feeds that run less than every six hours. Previously, an alert could stay open after a successful run if the recovery happened outside the recent-activity window. * **Overwatch**: [Equasis enrichment](/overwatch/api/vessels) no longer reports daily-cap rate-limiting as a pipeline failure on the [status page](/overwatch/status-page). Hitting a per-account daily query cap is normal rate-limit behavior, not an outage; cycles that bail on the cap are now logged as skipped runs rather than failed runs, so the failure-rate metric reflects real failures and the page stops showing red when enrichment is healthy but throttled. * **Overwatch**: Watchlist near-pass detection now fires on schedule. The detector's hourly cron was registered against an unset configuration parameter and aborted on every firing; the schedule now uses the standard helper that powers every other working cron in the codebase, so [near-pass alerts](/overwatch/api/alerts) flow without manual intervention. * **Overwatch**: More reliable [vessel enrichment](/overwatch/api/vessels) from Equasis on fresh logins. The first vessel in every batch was failing because the initial-login path skipped the session warm-up the re-login path already performed; the warm-up now runs in both paths, so registered owner, flag state, and deadweight tonnage populate consistently from the start of every run. * **Overwatch**: [AISHub bulk ingestion](/overwatch/ais-coverage) no longer drops entire batches in dense corridors. The poller now writes positions in 250-row chunks with a 50 ms breathing pause between chunks, so each statement finishes well under the database's 60-second timeout and the busiest geographies — NW Europe / Channel and the Strait of Hormuz / N Gulf — stop losing whole cluster fetches under contention. `ingestion_logs.status` gained a new `'partial'` value for runs where some chunks landed and others failed, with the per-chunk failure count surfaced as `metadata.chunks_failed`. If you query `ingestion_logs` directly, handle `'partial'` alongside `'success'` and `'failed'` — a partial run still wrote real data. * **Overwatch**: Live map controls no longer clip on shorter viewports. Trail playback controls now respect the browser's safe-area inset, the vessel-types legend reflows above the trail controls on shorter screens, and the viewport-loading disclaimer no longer overlaps the legend on desktop. See the [live map](/overwatch/getting-started). * **Layer**: New users no longer hit a dead-end "Unauthorized" or `no_tenant` screen when they reach Layer through paths that skip the standard sign-in callback. Workspaces now auto-provision on first dashboard load, on the [integration](/layer/integrations/overview) OAuth connect callback, and on the free [shadow IT scan](/layer/integrations/google-workspace) submission, so first-touch flows complete cleanly * **Layer**: Email/password sign-ups that included a workspace name now succeed end-to-end. A regression in the workspace-provisioning trigger was silently rolling back these accounts, so the browser appeared to confirm the sign-up but no account was created and no confirmation email arrived. [Getting started](/layer/getting-started) now works whether you sign up with Google, Microsoft, or email and password — if you tried earlier and never received a confirmation email, retry from [app.axiomlayer.io](https://app.axiomlayer.io) * **Layer**: When workspace provisioning fails during sign-up, the login page now shows the underlying reason inline instead of a generic "couldn't finish setting up your organization" message, so it's easier to tell whether to retry, contact support, or check your own configuration * **Layer**: Connecting an [integration](/layer/integrations/overview) immediately after sign-up no longer fails with a `save_failed` redirect. The OAuth callback now writes the connection through a tenant-authoritative path so the brand-new workspace is recognized on the first connect attempt instead of waiting for the session to refresh. If a write does fail in the future, the underlying reason is surfaced in the integrations banner instead of just the generic banner code, so the next step is obvious from the dashboard * **Layer**: Connector tiles on the [integrations](/layer/integrations/overview) catalog now show the right logo for every connector, including Microsoft, AWS, Jamf, and JumpCloud. The previous icon source 404'd on those marks because of trademark policy; logos now come from a comprehensive set with a colored-letter fallback for the long tail * **Layer**: Connected [integrations](/layer/integrations/overview) now show as **Connected** on the integrations page immediately after you finish the OAuth or credential flow, instead of re-rendering as **Connect** with no visible failure. The catalog read is now tenant-scoped through a verified path that matches the way the OAuth callback writes the connection, so saved connections appear on first refresh * **Locus**: NYC neighborhood coverage restored after the upstream NYC Open Data feed was withdrawn. Neighborhoods on cell [enrichment](/locus/api/enrichment), [scoring](/locus/scoring-conventions), and [location lookups](/locus/api/location-data) now resolve to the current 2020 Neighborhood Tabulation Areas — names like *East Village*, *Lower East Side*, and *Murray Hill-Kips Bay* — instead of falling back to *Manhattan Community Board 3* or similar administrative subdivisions. The OpenStreetMap fallback covering metros outside NYC now also identifies itself to the Overpass API, so curated polygons load reliably across all 22 supported metros * **Locus**: Neighborhood boundaries can now contain multiple disjoint polygons, so islands, exclaves, and peninsulas separated by water resolve correctly. Previously, multi-part shapes were silently truncated to their largest piece, which could miss matches in smaller components and fall back to a coarser administrative name * **Locus**: Signing in now drops you on the authenticated dashboard at `/dashboard` instead of the [explorer](https://locus.axiomancer.io/explore) map, and the explorer sidebar's **Back to Dashboard** link points to the same place instead of the marketing landing page * **Locus**: Cell scoring no longer reports synthetic "Safe" badges or fabricated permit-activity scores when the underlying data is missing. On the live [explorer](https://locus.axiomancer.io/explore), absence of crime data now cleanly omits the safety badge instead of showing a misleading 0-incident "safe" label, and a cell with no permit data is treated as no-signal in the development-pipeline group instead of being scored 0 out of 100. See [scoring conventions](/locus/scoring-conventions) * **Locus**: [Safety scores](/locus/scoring-conventions) no longer read as 100/100 when a FEMA flood zone is the only available sub-signal. The safety group now requires at least two sub-signals before producing a number, so cells without crime, environmental justice, NRI, air quality, or 311 data fall through to the standard no-signal value of 50 instead of letting the universally-present flood-zone-X source dominate. Cells with full safety coverage are unaffected * **Locus**: Tiny tracts no longer dominate the public [**Fastest-Growing Neighborhoods (Population)**](/locus/mcp-server) ranking. Census tracts with fewer than 1,000 prior residents are now filtered out so small-denominator anomalies — like an industrial-to-residential conversion that grew from 62 to 2,382 people and showed as +3,741% — don't push genuinely fast-growing inhabited neighborhoods off the leaderboard. Column labels and the list description were sharpened to match * **Layer**: New users without a workspace now go through an explicit **Create your workspace** step on first sign-in instead of having a workspace auto-named from their email domain. The previous behavior — silently binding a new user as owner of a brand-new "Gmail" or "Acme" workspace — was a tenant-hijack vector on invitee and SSO flows where the standard workspace-creation trigger hadn't fired. Existing workspaces, sign-ups that already include a workspace name, and users invited into an existing workspace are unaffected. See [Getting started](/layer/getting-started) * **Locus**: Every admin entrypoint — including the scoring-audit data fetcher — is now uniformly gated by the same email allowlist used by the rest of the admin surface. Previously, the audit dashboard's data route was protected only by "must be signed in," meaning any authenticated free-tier user could read its payload; non-allowlisted accounts now receive `403 Forbidden`. Self-hosted and preview deployments must populate the `ADMIN_EMAILS` environment variable with a comma-separated list of admin addresses — when unset, all admin pages and admin API routes fail closed for everyone, and the server logs a warning explaining how to populate it. Hosted Locus is unaffected * **Locus**: The batch [`/api/score/batch`](/locus/api/core-scoring) endpoint is now rate-limited and emits the same `X-RateLimit-Remaining` headers as `/api/cells`, `/api/pois`, and the rest of the metered surface, so it can no longer be used to fan out unbounded requests against the scoring backend. The 1-hour CDN cache on the route is unchanged, so repeat hits on the same H3 set still serve from the edge. Inbound H3 indexes are also validated before any database work, and plan-lookup outages now surface as a clean `503` instead of a 500 with leaked database error text * **Platform**: Closed 14 pre-existing access-control gaps across configuration, civic data, queued free-report jobs, lead capture, and operational telemetry tables. Read-only public reference data is now policy-protected at the row level, and sensitive operational state — including pending free-report submissions and inbound lead captures — is restricted to the service role, so customer-submitted data can no longer be read by other tenants under any circumstance * **Platform**: Brought the [Axiomancer Labs landing page](https://axiomancer.io) up to the same security-header baseline as Layer, Overwatch, Locus, and Codex. Every route now sets a Content-Security-Policy header (with `frame-ancestors 'none'` for clickjacking defense) tuned to the actual provider stack, alongside HSTS preload, `X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options`, and `Permissions-Policy`. Hosts in the CSP allowlist mirror the product sites, so headers stay consistent across the platform. * **Layer**: Hardened Stripe billing webhook handling on [Plans and billing](/layer/billing). Plan tier is now derived strictly from the Stripe price ID — editable subscription metadata is no longer trusted as the source of truth — and every webhook event is processed exactly once via an idempotency claim, so retried deliveries can no longer double-apply. Customer-to-organization binding is verified against the database mapping before any plan change takes effect, so a tampered metadata field can't bind an attacker's customer to a victim organization * **Layer**: Closed several findings from a cross-platform security review. Scheduled report email bodies now HTML-escape vendor, asset, and app names so a tenant admin can't plant a clickable link in another admin's inbox via a crafted vendor name. The scheduled-reports trigger token comparison is now timing-safe so it can't leak length or prefix-match information. The internal queue-stats token has a higher minimum length, and the AI Usage admin path no longer silently falls back to a lower-privilege key when its admin token is missing — failing closed with a clear error instead * **Overwatch**: More representative kinematic fingerprint samples behind [vessel risk scoring](/overwatch/api/risk) and behavioral analytics. The daily fingerprint-library job now samples vessel visits stratified across class and load-state buckets, so under-represented vessel profiles (such as light-displacement bulk carriers) are no longer crowded out of the reference library by the most-frequent buckets. Behavioral comparisons are more accurate as a result, especially for less common vessel types. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: Recalibrated [dark-event](/overwatch/api/risk) risk-tier thresholds against the actual production score distribution. This release described a downstream Sentinel-1 verification queue; that queue is not a currently supported production confirmation capability. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: This release described a Dempster-Shafer scoring correction for missing SAR observations. The current product does not claim SAR-verified dark events; its [Sentinel endpoint](/overwatch/api/sar-coverage) reports catalog metadata only. * **Layer**: Connector tiles on the [integrations](/layer/integrations/overview) catalog now flip to **Connected** the moment an OAuth callback or credential save completes, instead of staying on **Connect** until a session refresh. The card's read previously couldn't see its own freshly-written row through row-level security, so newly-connected integrations looked unconnected even though the saved credential was already in place. Reconnect retries are no longer needed — the tile reflects the real state on the next page load. * **Layer**: Failed Stripe payments now flip the relevant subscription to **past\_due** after three consecutive failed attempts on [Plans and billing](/layer/billing), restoring an `invoice.payment_failed` lifecycle hook that briefly went silent during the recent webhook consolidation. Successful retries clear the state automatically. No action is required if your subscription is current. * **Layer**: Scheduled reports no longer double-send when the cron loop runs twice in the same window. Previously, a Vercel cron retry, a manual overlap, or a multi-region replica race could pick up the same due schedule and email recipients twice; each scheduled send is now claimed exactly once per `(schedule, scheduled-for)` window before any email goes out, so duplicate runs cleanly skip rather than re-deliver. Send timing and recipient lists are otherwise unchanged. * **Codex**: Tightened the Content-Security-Policy on [axiomcodex.io](https://axiomcodex.io) to drop `unsafe-eval` from `script-src`. The marketing site no longer permits runtime code evaluation in the browser, closing a class of script-injection paths without affecting any user-facing functionality. No action is required on your part for any of the fixes above. # May 2, 2026 (/changelog/2026-05-02) ## Redesigned Layer landing page [#redesigned-layer-landing-page] The Layer landing page has been completely rebuilt with a looping video hero, animated feature spotlights, an integration wall showing supported connectors, a how-it-works walkthrough, and an FAQ section. The new page gives prospective users a clearer picture of what Layer does before signing up. ## Redesigned Codex landing page [#redesigned-codex-landing-page] The Codex landing page now features a full-screen video hero section, giving visitors an immediate visual overview of the platform's compliance automation capabilities. ## Improved onboarding wizard [#improved-onboarding-wizard] The step-by-step onboarding flow now names specific providers for each category — [Google Workspace](/layer/integrations/google-workspace), [Microsoft 365](/layer/integrations/microsoft-365), Brex, Ramp, QuickBooks, [Jamf](/layer/integrations/jamf), [Intune](/layer/integrations/intune), Rippling, Gusto, BambooHR, and Deel — so you know exactly what's available without navigating to the [integrations](/layer/integrations/overview) page first. Steps also use "Sign in" language to reflect the one-click OAuth experience rather than manual API token entry. # May 5, 2026 (/changelog/2026-05-05) ## Pairwise encounter extraction reliable again [#pairwise-encounter-extraction-reliable-again] Resolved a silent failure in the [pairwise encounter extraction](/overwatch/methodology/encounter-extraction) pipeline. The hourly job was timing out on every run for \~24 hours after duplicate indexes on the encounter table pushed write batches past the database statement timeout. The duplicate indexes have been dropped and upsert batches halved as a safety margin. Encounter geometry — CPA, TCPA, range, closing speed, COLREGS rule and role posteriors, and Rule 17 deviation flags — is flowing into the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs again with full hourly freshness. No action is required on your part; backfill of the gap window is in progress. ## Hardened webhook URL validation [#hardened-webhook-url-validation] Webhook URL validation on [alert channels](/overwatch/api/alerts) is now stricter — only `https://` destinations on the public internet are accepted, with explicit rejection of internal hostnames, link-local ranges, and other non-routable addresses. Existing webhook subscriptions are unaffected; new and updated subscriptions return a clear error message when an invalid URL is submitted instead of silently accepting it. ## Better error details on the public positions endpoint [#better-error-details-on-the-public-positions-endpoint] The public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint now preserves and returns underlying error details when an upstream component fails, instead of collapsing to a generic 500. API consumers building live maps and dashboards on top of the endpoint can now distinguish between transient upstream issues and request-side problems without having to retry blindly. ## Tightened security headers and cron authentication [#tightened-security-headers-and-cron-authentication] Hardened the security headers served on every [axiomoverwatch.io](https://axiomoverwatch.io) response, and tightened authentication on the internal cron endpoints that drive ingestion, archival, alert delivery, and Locus portfolio refresh. No user-facing behavior changes; browsers benefit from the stricter Content-Security-Policy and related headers automatically. ## Coordinated mobile polish across every Axiom site [#coordinated-mobile-polish-across-every-axiom-site] [axiomoverwatch.io](https://axiomoverwatch.io), [axiomlayer.io](https://axiomlayer.io), [locus.axiomancer.io](https://locus.axiomancer.io), [axiomcodex.io](https://axiomcodex.io), and [axiomancer.io](https://axiomancer.io) all received a coordinated mobile polish pass — landing pages, ticker rows, marketing sections, and the cross-product navigation bar no longer overflow the viewport, introduce horizontal scroll, or clip on small breakpoints. The Rogue Stack mobile landing nav also lands in this pass. ## RouteShift link in cross-product bar points to the live app [#routeshift-link-in-cross-product-bar-points-to-the-live-app] The **RouteShift** entry in the cross-product navigation bar across [axiomoverwatch.io](https://axiomoverwatch.io), [axiomlayer.io](https://axiomlayer.io), [locus.axiomancer.io](https://locus.axiomancer.io), [axiomcodex.io](https://axiomcodex.io), and [axiomancer.io](https://axiomancer.io) now points to [routeshift.io](https://routeshift.io) — the canonical live domain — so clicks from anywhere in the platform reach the LLM proxy gateway directly instead of dead-ending at an unowned domain. ## SEO, sitemap, and analytics polish on Overwatch and Axiomancer [#seo-sitemap-and-analytics-polish-on-overwatch-and-axiomancer] [axiomoverwatch.io](https://axiomoverwatch.io) and [axiomancer.io](https://axiomancer.io) both received a professionalization pass — branded OpenGraph and Twitter `summary_large_image` social previews, a `robots.txt` and `sitemap.xml` at site root, refreshed alt text on marketing imagery, and analytics gating so PostHog and Amplitude only initialize on consent. Links unfurl with full-bleed branded previews on Slack, X, LinkedIn, and any embed-friendly surface, and search engines can index the public marketing surface without relying on link traversal. ## Faster Axiomancer hero video [#faster-axiomancer-hero-video] The hero video on [axiomancer.io](https://axiomancer.io) is now optimized for first paint — the heavier Mux player has been replaced on the homepage with a leaner asset path, mobile rendering of the hero is sharper, and the optimized hero is wired through to the rest of the marketing surface. First-time visitors on mobile see the hero noticeably sooner. # May 6, 2026 (/changelog/2026-05-06) ## Per-port water density ingestion for hydrostatic cargo estimates [#per-port-water-density-ingestion-for-hydrostatic-cargo-estimates] The water density adjustment in [cargo validation](/overwatch/methodology/cargo-validation#water-density-sources) now runs on real, port-specific surface measurements instead of a global default. A new monthly ingestion seeds one density reading per port from a tiered NOAA chain: real-time temperature and salinity from **NOAA CO-OPS** stations for US ports with co-located gauges (currently New Orleans and Houston), **NOAA World Ocean Atlas 2023** annual surface climatology via NCEI ERDDAP for all other ports globally, and published per-country climatological constants as a final fallback when both NOAA endpoints are unreachable. Density is computed from temperature and salinity using the **UNESCO-80** seawater equation of state at surface pressure and stored per port at H3 resolution 8 along with its source identifier, so hydrostatic cargo estimates remain reproducible against the exact density value that was used at the time. The job runs on the 1st of each month at 03:30 UTC, with rows older than 90 days pruned automatically. Hydrostatic-equipped vessels arriving at brackish or low-salinity ports — Rotterdam, the Elbe, the Mississippi delta — should see the largest accuracy gains; deep-saltwater ports were already close to the previous default. No action is required on your part. The full source chain and tier table are documented under [cargo validation methodology](/overwatch/methodology/cargo-validation#water-density-sources). ## POI collection back on a 6-hourly schedule [#poi-collection-back-on-a-6-hourly-schedule] The `collect-pois` and `collect-pois-premium` ingestion crons that populate `poi_snapshots` had been pinned to a once-a-year schedule, which caused the **Nearby POIs** rail in the [Explorer](/locus/explorer), the [`GET /api/pois`](/locus/api/location-data) endpoint, and the POI counts in [`GET /api/enrich`](/locus/api/enrichment) and the [discovery and intelligence](/locus/api/discovery-and-intelligence) endpoints to gradually drift up to 35+ days stale. Both crons now run at **00:00, 06:00, 12:00, and 18:00 UTC daily**, matching the rest of the Locus collector slot rotation. POI inventory freshness on the [data freshness table](/locus/scoring-conventions) returns to its documented `<7 days` window, and the Explorer's POI accordion will reflect new openings and closures within hours rather than months. No action is required on your part — backfill of the gap window is in progress. ## APRS backfills scheduled for three zero-coverage tables [#aprs-backfills-scheduled-for-three-zero-coverage-tables] The three Locus catalog tables still showing **0% APRS envelope coverage** on the [envelope coverage dashboard](/codex/envelope-coverage) — `uscis_h1b_employers`, `usda_nass_county_crops`, and `muckrock_foia_requests` — now have nightly backfill jobs scheduled in the 03:30–03:40 UTC low-traffic window. The backfill functions themselves were already in production; today's change wires them into pg\_cron so they actually run. Coverage on these tables will climb toward 100% over the next several nightly cycles, after which they'll join the rest of the Locus catalog in the [`aprs.civic`, `aprs.commodity`, and `aprs.permits`](/locus/data-standards) profile rosters with full envelope-driven joinability and incremental sync. No action is required on your part; the dashboard is the canonical place to watch progress. ## Mobile, SEO, security, and analytics polish on Locus [#mobile-seo-security-and-analytics-polish-on-locus] [locus.axiomancer.io](https://locus.axiomancer.io) received the same professionalization pass [Overwatch and Axiomancer landed yesterday](/changelog/2026-05-05) — a stricter `Content-Security-Policy`, `Strict-Transport-Security` with preload, and a `Permissions-Policy` that disables camera, microphone, geolocation, and FLoC by default; refreshed alt text and tap-target sizing on the marketing surface (mobile links and the **Get Access** button now meet the 44 px minimum); a PWA manifest with branded icon and theme color so the site installs cleanly on mobile home screens; and analytics gating that suppresses PostHog session recording outside of production and on `/admin` and `/settings` routes. The Locus marketing pages also now declare `neighborhood analytics` and `demographic data` as additional keywords for discovery. No user-facing behavior changes for authenticated workflows — the Explorer, dashboard, and API surface are unchanged. ## Course-alteration anomaly detection now live in production [#course-alteration-anomaly-detection-now-live-in-production] The course-alteration anomaly detector — first announced in [the April 26–May 2 weekly recap](/changelog/2026-05-02-weekly) and integrated into the [unified alerts inbox](/overwatch/api/alerts) on [May 16](/changelog/2026-05-16-weekly) — was wired into the wrong worker entry point and had been silently skipped on every position update since launch. The detector is now invoked from the production ingest worker, and `course_alteration` events are flowing into [`axiom_events`](/overwatch/api/risk) for the first time. Behavior matches what was already documented: * Fires when an underway vessel deviates **45° or more** from its rolling 6-hour mean heading * Suppresses detections within **10 km** of any port zone, so legitimate maneuvering near port doesn't generate noise * Ignores stationary vessels (≤ 0.5 kt) * Per-vessel **6-hour deduplication window**, so a single sustained turn produces one event rather than a flood Detected counts are also reported on the worker's cockpit heartbeat as `course_alterations_detected`, so the [`/workers`](/overwatch/api/alerts) view in the cockpit can confirm the detector is healthy at a glance. The companion `worker_inactive` self-monitor [shipped on May 9](/changelog/2026-05-09-weekly) will now resolve as events resume landing, and the [Ghost Vessels](/overwatch/api/alerts) reverse-COLREGS inference cron — which depends on `course_alteration` as its input signal — has live data to reason over for the first time. No action is required on your part. If you previously subscribed a watchlist or your full fleet to the **Course alteration** alert-rule template, those rules will start dispatching as events arrive. # May 7, 2026 (/changelog/2026-05-07) ## Dashboard sign-in goes straight to Google Workspace [#dashboard-sign-in-goes-straight-to-google-workspace] The [Layer dashboard](https://app.axiomlayer.io) login page now starts a Google Workspace OAuth flow directly instead of routing through Auth0 Universal Login. Click **Continue with Google Workspace** on the sign-in page, approve on Google's consent screen, and you land in the dashboard with a Supabase session — no Auth0 detour and no callback loop back to the login page. Previously the dashboard's "Sign in with Auth0" entrypoint sent users into Auth0, but the dashboard middleware and layout require a Supabase session. After Auth0 login, users did not receive the Supabase cookies the dashboard needs, so the dashboard appeared broken or bounced back to login. The new entrypoint completes the Supabase OAuth handshake and sets the dashboard cookies in one step. Auth0 delegation is unchanged for `/auth/login` and for [integration OAuth flows](/layer/integrations/overview) — Slack, Atlassian, and the other connectors that broker through Auth0 keep working exactly as before. Only the dashboard sign-in entrypoint moved. No action is required on your part; the next sign-in will use the new flow automatically. ## Locus admin authorization prefers stable user IDs and role claims [#locus-admin-authorization-prefers-stable-user-ids-and-role-claims] Locus admin authorization now resolves through stable identity claims first and only falls back to the email allowlist for compatibility. Self-hosted and preview deployments can pin `/admin/*` access — pages and admin API routes alike — to immutable Supabase user IDs or to explicit role claims on `app_metadata` / `user_metadata`, instead of relying on the email address an identity provider happens to surface for a given account. Two new environment variables drive the new paths, and both are checked before `ADMIN_EMAILS`: * `ADMIN_USER_IDS` — comma-separated list of Supabase user UUIDs. The most robust option: a user's ID never changes when they rotate their email, get aliased through SSO, or move providers. Authorized users are matched case-insensitively against `user.id`. * `ADMIN_ROLE_CLAIMS` — comma-separated list of role names. Any of `role`, `roles`, `admin_role`, `admin_roles`, `app_role`, or `app_roles` on `app_metadata` or `user_metadata` (string or string array) can carry the claim, so however your identity provider stamps roles into Supabase will work without extra mapping. Comparison is case-insensitive. ```bash # Preferred: pin admin to immutable Supabase user IDs ADMIN_USER_IDS=00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002 # Or: authorize anyone whose JWT carries `role: "admin"` (or `roles: ["admin", ...]`) ADMIN_ROLE_CLAIMS=admin,ops # Legacy fallback — still works, but logs a warning per request ADMIN_EMAILS=alice@example.com,bob@example.com ``` The order of precedence is `ADMIN_USER_IDS` → `ADMIN_ROLE_CLAIMS` → `ADMIN_EMAILS`. If none of the three are configured, every admin page and admin API route continues to fail closed and the server logs a warning telling you which variables to populate. When access is granted via the legacy `ADMIN_EMAILS` path, the server now also logs a per-request warning naming the user ID, so you can audit who is still relying on email-based authorization before you remove the variable. No action is required if you only consume Locus through the [authenticated API](/locus/api/overview); only operators of self-hosted and preview deployments need to set the new variables. Existing `ADMIN_EMAILS` configurations keep working unchanged — set `ADMIN_USER_IDS` or `ADMIN_ROLE_CLAIMS` alongside (or instead of) `ADMIN_EMAILS` when you want admin access to survive an email change at your identity provider. ## Overwatch admin auth gains least-privilege paths [#overwatch-admin-auth-gains-least-privilege-paths] Admin authorization for sensitive Overwatch endpoints — [API key management](/overwatch/api/admin), [billing webhooks](/overwatch/api/webhooks), and other operator-only routes — now resolves through stable identity claims and scoped machine secrets first, with the broad `ADMIN_API_KEY` retained only as a compatibility fallback. Self-hosted and preview deployments can pin admin access to immutable Supabase user IDs, to explicit role claims on `app_metadata`, or to dedicated per-automation machine keys, instead of relying on a single shared admin secret. Three new environment variables drive the new paths, and all three are checked before `ADMIN_API_KEY`: * `ADMIN_USER_IDS` — comma-separated list of Supabase user UUIDs. The most robust option: a user's ID never changes when they rotate their email, get aliased through SSO, or move providers. Authorized users are matched case-insensitively against `user.id` on the active Supabase session. * `ADMIN_ROLE_CLAIMS` — comma-separated list of role names. Any of `role`, `roles`, `admin_role`, `admin_roles`, `app_role`, or `app_roles` on **`app_metadata`** (string or string array) can carry the claim. `user_metadata` is intentionally **not** trusted here, because it is commonly user-writable in Supabase and must not grant admin. Comparison is case-insensitive. * `ADMIN_MACHINE_KEYS` — comma-separated list of scoped machine secrets, presented in the `X-API-Key` or `Authorization: Bearer …` header just like the legacy `ADMIN_API_KEY`. Multiple secrets are supported so each automation, cron, or webhook signer can carry its own credential and be rotated independently. Comparison is **case-sensitive** to preserve full secret entropy and uses a constant-time hash compare. ```bash # Preferred: pin admin to immutable Supabase user IDs ADMIN_USER_IDS=00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002 # Or: authorize anyone whose JWT carries `role: "admin"` on app_metadata ADMIN_ROLE_CLAIMS=admin,ops # Per-automation machine secrets — one per caller, rotate independently ADMIN_MACHINE_KEYS=svc-billing-webhook-…,svc-cron-runner-… # Legacy fallback — still works, but prefer the scoped variables above ADMIN_API_KEY=legacy-shared-secret ``` The order of precedence is `ADMIN_USER_IDS` → `ADMIN_ROLE_CLAIMS` → `ADMIN_MACHINE_KEYS` → `ADMIN_API_KEY`. If none of the four are configured, `requireAuth` continues to fail closed with `403 Admin access not configured`. Authenticated requests that don't match any configured path return `401 Unauthorized`. The per-IP rate limit on admin auth attempts is unchanged — 10 attempts per minute, returning `429 Too many auth attempts` past the threshold — and the constant-time hash compare on machine secrets is preserved across both `ADMIN_MACHINE_KEYS` and the legacy `ADMIN_API_KEY` path. No action is required if you only consume Overwatch through the [public REST API](/overwatch/api/overview) with a regular `X-API-Key`; the admin paths only gate operator-level routes. Only operators of self-hosted and preview deployments need to set the new variables. Existing `ADMIN_API_KEY` configurations keep working unchanged — set `ADMIN_USER_IDS`, `ADMIN_ROLE_CLAIMS`, or `ADMIN_MACHINE_KEYS` alongside (or instead of) `ADMIN_API_KEY` when you want admin access tied to a real identity or split into per-caller machine credentials. ## Location names escaped in Locus free-report confirmation emails [#location-names-escaped-in-locus-free-report-confirmation-emails] The confirmation email sent to recipients of a [free Location Report](https://locus.axiomancer.io/free-report) now HTML-escapes the geocoded place name before interpolating it into the email body, closing a path where a maliciously crafted Mapbox `place_name` could inject markup into the rendered confirmation message. The email subject line continues to render the place name as readable text with control characters stripped. No user-facing behavior changes for legitimate report requests — place names render normally in both the subject and body. No action is required on your part. ## Provider authentication required to commit virtual-card authorizations [#provider-authentication-required-to-commit-virtual-card-authorizations] The [virtual-card](/layer/spend-management) authorization endpoint now requires a provider-authenticated request before it will commit a balance change. Dashboard and session-based callers can still POST to the endpoint to evaluate an authorization against the configured spend limit, but the response now returns `committed: false` and the running spend total is left untouched. Only the card provider — currently Stripe Issuing — can drive a real commit by presenting the shared `x-virtual-card-provider-secret` header on the webhook callback. This closes a path where an authenticated dashboard user could call the endpoint with `commit: true` and move the cumulative spend total without any provider-side authorization actually clearing. Read-only evaluation flows from the dashboard are unchanged. No action is required on your part — existing webhook subscriptions continue to work, and per-vendor spend caps, limit windows, and the [audit log](/layer/audit-log) entries on virtual-card events are unaffected. ## Tightened production CSP on the Layer dashboard [#tightened-production-csp-on-the-layer-dashboard] Hardened the production Content-Security-Policy on the [Layer dashboard](https://app.axiomlayer.io) — `'unsafe-eval'` is no longer permitted in `script-src` outside local development. `'unsafe-inline'` is retained in production so Next.js App Router hydration and RSC bootstrap scripts continue to run; without it, dashboard pages render as static HTML and client components — including the **Continue with Google Workspace** button — never hydrate. `'unsafe-eval'` stays scoped to development builds so the local `next dev` workflow keeps working, while production responses now serve the stricter policy on every route. The other security headers shipped alongside CSP — `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, and a `Permissions-Policy` that disables camera, microphone, and geolocation — are unchanged. No user-facing behavior changes. Existing [integrations](/layer/integrations/overview), [billing](/layer/billing), embedded video, and the support widget continue to work, and browsers benefit from the stricter `script-src` automatically on the next page load. No action is required on your part. ## Removed HSTS `preload` directive from Layer apps [#removed-hsts-preload-directive-from-layer-apps] Dropped the `preload` directive from the `Strict-Transport-Security` header on the [Layer dashboard](https://app.axiomlayer.io) and the Rogue Stack app surface. The header now serves `max-age=63072000; includeSubDomains` — a two-year HTTPS-only commitment that still applies to the apex domain and every subdomain — without advertising readiness for the browser preload list. The preload directive is a one-way promise: once a domain is submitted to the [HSTS preload list](https://hstspreload.org/), browsers refuse plaintext HTTP to it (and every subdomain) before the first request. Removing the directive in code is a prerequisite for stepping back out of that commitment cleanly, and lets us hold off on submission until every operational subdomain — including any internal tooling that may not yet terminate TLS — has been independently verified to serve HTTPS. No browser-facing behavior changes for traffic that's already on HTTPS, which is every production route on Layer. Browsers still upgrade `http://` requests for the next two years and continue to refuse mixed content. The directive can be re-added in a follow-up rollout once subdomain HTTPS coverage is confirmed end-to-end. No action is required on your part. ## Dashboard tables ignore nested controls and stay on in-range pages [#dashboard-tables-ignore-nested-controls-and-stay-on-in-range-pages] Tables across the [Layer dashboard](https://app.axiomlayer.io) — integrations, spend, access reviews, contracts, and friends — now feel right on the edges they used to bite. Clicking a checkbox, button, link, menu, dropdown, or other interactive control nested inside a row no longer also fires the row's primary navigation, so opening a row menu or selecting a row's checkbox stops short of also drilling into the row. Paginated tables also clamp to the last available page when filters or data changes would otherwise leave you stranded on an empty out-of-range page, so toggling a filter on a deep page lands you on real rows instead of a blank table. No action is required on your part. The change applies automatically to every list view in the dashboard. ## Hardened post-login `next` redirect handling [#hardened-post-login-next-redirect-handling] The post-login `next` redirect on the [Layer dashboard](https://app.axiomlayer.io) sign-in page and the Supabase OAuth callback now decode the parameter before validating it and reject anything that isn't a same-origin path. Encoded protocol-relative payloads (for example `%2F%2Fexample.com`), backslash-prefixed forms, and control characters all fall back to `/dashboard` instead of bouncing the browser to an attacker-controlled destination. The shared helper is reused by the email/password sign-in path, the **Continue with Google Workspace** button, and the Supabase OAuth callback, so all three flows enforce the same allowlist. No user-facing behavior changes for legitimate sign-ins — same-origin `next` paths under `/` still resolve as before. No action is required on your part. ## Public API proxy matches only declared prefixes [#public-api-proxy-matches-only-declared-prefixes] The public API surface on the [Layer dashboard](https://app.axiomlayer.io) now only matches a request when the path is an exact declared prefix or a child path beneath it, instead of any path that happens to share the same opening characters. Requests that previously slipped through on a coincidental string match — for example, a path that began with the same letters as a public API prefix but was a sibling rather than a child — now fall through to the authenticated dashboard surface as intended. No user-facing behavior changes for legitimate API consumers; existing endpoints under [`/api/mcp`](/layer/mcp-server), the [discovery extension](/layer/browser-extension), and the rest of the public surface continue to work unchanged. ## Hardened Content-Security-Policy and Permissions-Policy on Locus [#hardened-content-security-policy-and-permissions-policy-on-locus] Extended the security-header pass that landed on the Locus marketing surface [yesterday](/changelog/2026-05-06) across the entire authenticated app at [locus.axiomancer.io](https://locus.axiomancer.io). The Content-Security-Policy now includes explicit clickjacking, base-tag, and form-action defenses (`frame-ancestors 'none'`, `base-uri 'self'`, `object-src 'none'`, `form-action 'self'`) and an allowlist tuned to the actual provider stack the [Explorer](/locus/explorer), [dashboard](/locus/dashboard), and API console rely on — Supabase (REST and realtime), Mapbox tiles, Sentry, PostHog, Amplitude, Mixpanel, Intercom, Stripe Checkout, and Mux video. The obsolete `X-XSS-Protection` header has been removed; modern browsers ignore it and certain values can introduce their own bugs, so CSP is the canonical defense going forward. `Permissions-Policy` now denies a much broader set of powerful browser APIs by default — accelerometer, ambient light, autoplay, battery, camera, display capture, encrypted media, geolocation, gyroscope, magnetometer, microphone, MIDI, payment, picture-in-picture, public-key credentials, screen wake lock, USB, web share, and XR spatial tracking — with `fullscreen` scoped to first-party only. None of these APIs were ever used by Locus features, so no in-app workflow is affected; the policy just makes the lack of access explicit at the browser level. `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin` continue to be served on every response. No user-facing behavior changes — the Explorer rails, [neighborhood scoring](/locus/scoring-conventions) panels, [API console](/locus/api/overview), Stripe checkout, Mapbox-rendered maps, and embedded video all work as before. Browsers benefit from the stricter policy automatically on the next page load. No action is required on your part. ## DB-level idempotency for AIS positions and port events [#db-level-idempotency-for-ais-positions-and-port-events] The Overwatch live database now enforces insert idempotency for [`ais_positions`](/overwatch/api/vessels) and [`port_events`](/overwatch/api/ports) at the row level, so AIS workers and Edge Functions can retry batches after transient errors without producing duplicate rows. A `BEFORE INSERT` trigger on each table now skips an incoming row when a matching record already exists, rather than failing the insert with a unique-constraint violation. Two stable identities are checked in order: * **`record_id`** — when the incoming row carries a non-empty stable APRS URN (the same `record_id` documented on the [ports schema](/overwatch/api/ports)), an existing row with the same `record_id` causes the new insert to be silently skipped. * **Natural key** — for AIS positions, the tuple `(source, imo_number, timestamp)`. For port events, the tuple `(imo_number, port_id, event_type, timestamp)`. If a row with the same natural key is already present, the incoming row is skipped. Concurrent inserts for the same identity are serialized with a transaction-scoped advisory lock taken before the duplicate probe, so two parallel workers cannot both pass the check before either row is visible. Existing indexes on `ais_positions(record_id)`, `ais_positions(imo_number, timestamp)`, `ais_positions(source, timestamp)`, `port_events(record_id)`, and `port_events(port_id, imo_number, timestamp desc)` already cover the duplicate probes — no new indexes are added by this change. What this means for ingestion observability: the duplicate-key path that surfaced as a `23505` error in the [VesselFinder ingestion `partial` example below](#vesselfinder-ingestion-surfaces-per-batch-db-write-failures-as-partial) will no longer appear in `metadata.db_write_errors`. Skipped duplicates are not failures — they are absorbed by the trigger and counted toward `records_stored` only on the first successful insert. Retry-driven re-runs of an AIS or port-events batch are now safe to call repeatedly without inflating row counts or generating spurious partial-status runs. No user-facing behavior changes for [public REST API](/overwatch/api/overview) consumers — vessel positions and port events continue to flow into the live database, and [data retention](/overwatch/data-retention) windows are unaffected. No action is required on your part. ## VesselFinder ingestion surfaces per-batch DB write failures as `partial` [#vesselfinder-ingestion-surfaces-per-batch-db-write-failures-as-partial] The Overwatch VesselFinder ingestion job now reports database write failures explicitly instead of swallowing them. Previously, if the `vessels` upsert or the `ais_positions` insert returned a Postgres error mid-run, the run would still complete with `status: 'success'` in [`ingestion_logs`](/overwatch/methodology/encounter-extraction) and `records_stored` would silently exclude the failed rows, leaving operators with no signal that anything was wrong. Each failed batch is now captured with its operation, message, code, details, and hint, written to the `ingestion_logs` row in `metadata.db_write_errors` and joined into the `error` column. When at least one batch fails but others succeed, the run lands as `status: 'partial'` — matching the convention already used by the [route-forecasts cron](/overwatch/methodology/route-forecasts) — and the HTTP response returns `207 Multi-Status` with the same `db_write_errors` array in the body. Runs where no batches fail still return `200` with `status: 'success'`, and runs that throw before any batch is attempted still return `500` with `status: 'failed'` and any partial errors collected up to that point preserved in `metadata.db_write_errors`. ```json { "fetched": 4820, "stored": 4612, "ports": 12, "status": "partial", "db_write_errors": [ { "operation": "ais_positions insert", "message": "duplicate key value violates unique constraint", "code": "23505", "details": "Key (mmsi, timestamp) already exists.", "hint": null } ] } ``` No user-facing behavior changes for [public REST API](/overwatch/api/overview) consumers — vessel data continues to flow into the live database — and operators monitoring [`ingestion_logs`](/overwatch/status-page) gain visibility into transient batch failures that were previously invisible. No action is required on your part. ## Database-level idempotency for AIS positions and port events [#database-level-idempotency-for-ais-positions-and-port-events] Overwatch ingestion is now idempotent at the database layer for [`ais_positions`](/overwatch/api/vessels) and [`port_events`](/overwatch/api/ports). Duplicate `INSERT`s for the same row — whether driven by [VesselFinder ingestion retries](/overwatch/methodology/encounter-extraction), historical backfill, or `process-events` re-runs — are now skipped silently by a `BEFORE INSERT` trigger instead of either succeeding twice or surfacing as `duplicate key value violates unique constraint` errors in [`ingestion_logs`](/overwatch/status-page). Each incoming row is matched against an existing row in two passes: * If `record_id` is non-empty, the trigger looks up that `record_id` and skips the new row when one already exists. `record_id` is the stable provenance identifier already documented on [`port_events`](/overwatch/api/ports) (`Stable APRS URN for deduplication and audit trails`) and now governs duplicate suppression for AIS positions on the same basis. * Otherwise, the trigger falls back to a stable natural key. AIS positions dedupe on `(source, imo_number, timestamp)`. Port events dedupe on `(imo_number, port_id, event_type, timestamp)`. A transaction-scoped advisory lock serializes the duplicate check on each identity, so two concurrent workers attempting to insert the same row cannot both pass the check before either row becomes visible. The check is bounded to the duplicate probe and released at commit, so unrelated writes are unaffected. ```json { "fetched": 4820, "stored": 4612, "ports": 12, "status": "success", "db_write_errors": [] } ``` For consumers of the [public REST API](/overwatch/api/overview), nothing changes — vessel and port-event reads return the same rows they did before, just without the rare duplicate that previously slipped through during retry storms. Operators monitoring [`ingestion_logs`](/overwatch/status-page) will see fewer `duplicate key` entries in the `db_write_errors` array introduced by today's [VesselFinder ingestion fix](#vesselfinder-ingestion-surfaces-per-batch-db-write-failures-as-partial), since duplicate inserts no longer reach the `INSERT` itself. No action is required on your part. ## River-level fetcher resolves port slugs to UUIDs before writing [#river-level-fetcher-resolves-port-slugs-to-uuids-before-writing] The Overwatch [river-levels](/overwatch/api/river-levels) ingestion job now resolves port slugs to real `ports.id` UUIDs before writing readings into `port_weather`, instead of stuffing the slug string into the `port_id` column. Previously, the `port_weather` upsert used `r.port_slug` directly as `port_id`, which silently failed the foreign-key relationship to `ports` and produced rows that no downstream join — port detail pages, alerting, congestion analytics — could resolve back to a real port. The function now batches all distinct slugs from a run into a single `select id, slug from ports where slug in (...)`, builds a slug→UUID map, and skips any reading whose slug doesn't resolve. Unresolved slugs are logged server-side and returned in a new `missing_port_slugs` array on the response so operators can see immediately when a slug in the source feed has drifted from the `ports` catalog. The original slug is preserved on each successfully written row in `metadata.port_slug` for traceability. The upsert key is unchanged (`port_id, forecast_time`), so re-running the job continues to deduplicate cleanly. ```json { "stored": 9, "alerts": ["MISS_LOWER: River: Lower Mississippi at 4.8 ft (low)"], "missing_port_slugs": ["new-orleans-temp"], "readings": [...] } ``` No user-facing behavior changes for [`/api/v1/river-levels`](/overwatch/api/river-levels) consumers — the public read endpoint already returns gauge readings directly and is unaffected. The fix improves the correctness of derived data in `port_weather`, so downstream port and congestion endpoints that join against river readings now return rows for the right ports. No action is required on your part. ## Email verification confirmation page escapes the recipient address [#email-verification-confirmation-page-escapes-the-recipient-address] The Overwatch email-channel verification confirmation page at `/api/v1/alerts/channels/email/verify` now HTML-escapes the recipient email address before interpolating it into the rendered confirmation HTML. Both the "Already verified" and "Verified" pages run the stored `email_to` value through an entity escape for `&`, `<`, `>`, `"`, and `'` before it lands in the response, closing a path where a maliciously crafted address persisted into `alert_email_verifications` could inject markup into the page rendered to the verifying recipient. Legitimate addresses render normally — `alice@example.com` continues to display as plain text in bold — and the magic-link verification flow itself is unchanged: recipients still click through from the verification email, land on the confirmation page, and have the corresponding [email channel](/overwatch/api/alerts) marked active. No action is required on your part. ## Sentry PII and server-side local variables disabled outside development [#sentry-pii-and-server-side-local-variables-disabled-outside-development] Overwatch Sentry initialization across the client, edge, and server runtimes no longer captures personally identifiable information by default in production. `sendDefaultPii` is now `false` on all three Sentry clients — previously the Next.js wizard default of `true` meant Sentry would attach IP addresses, request headers, cookies, and user-context fields to every event. Server-side `includeLocalVariables` is also now scoped to `NODE_ENV === 'development'`, so production stack frames no longer carry the surrounding local-variable snapshot that could include API keys, query parameters, or per-request secrets read into local scope. Error reporting itself is unchanged: production exceptions still flow to Sentry with full stack traces, request URLs, and the existing `enableLogs: true` console forwarding for middleware and edge-runtime errors. Trace and replay sample rates (`tracesSampleRate`, `replaysSessionSampleRate`, `replaysOnErrorSampleRate`) are unchanged. Local development still receives full PII and local-variable snapshots so debugging in a `next dev` run keeps working exactly as before. No user-facing behavior changes. Operators of self-hosted and preview deployments who relied on PII fields in Sentry events for incident triage can opt in per-environment by setting `sendDefaultPii: true` in their own Sentry init overrides — but the default for production is now privacy-preserving. No action is required on your part. ## Provider authentication required for virtual card authorization commits [#provider-authentication-required-for-virtual-card-authorization-commits] Tightened the [virtual card](/layer/spend-management) authorization endpoint so that only the card provider — not ordinary dashboard or session users — can commit authorization rollups against a card's hard limit. Requests from authenticated users without the provider secret now run as a read-only evaluation: the response still returns the approval decision and remaining balance, but `committed` is `false` and the spend rollup is left untouched. To commit a rollup, the caller must pass a matching shared secret in the `x-virtual-card-provider-secret` header. Layer looks up the secret per provider (for example, `VIRTUAL_CARD_AUTH_STRIPE_ISSUING_SECRET` for `stripe_issuing`) and falls back to `VIRTUAL_CARD_AUTH_WEBHOOK_SECRET` or the existing `STRIPE_ISSUING_WEBHOOK_SECRET`. Comparison is constant-time. If no secret is configured for the provider, commits are rejected with `403 Provider authentication required for committed authorizations`. Existing webhook deliveries from your card provider continue to work as long as the matching secret is set in your environment — no dashboard changes are required. # May 8, 2026 (/changelog/2026-05-08) ## Microsoft Teams, Atlassian, and Workday HRIS connectors [#microsoft-teams-atlassian-and-workday-hris-connectors] Three new connectors are live on the [Layer integrations catalog](/layer/integrations/overview): * **Microsoft Teams** — discovers Teams as a SaaS app and inventories every user with their last activity, so dormant Teams licenses surface alongside the rest of your seat data. * **Atlassian (Jira & Confluence)** — one OAuth sign-in covers both products. Per-user last-active times feed [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding), and each connected Atlassian product (Jira, Confluence, and the rest) shows up as its own SaaS app in the inventory. See [Atlassian integration](/layer/integrations/atlassian). * **Workday HRIS** — paginated worker sync with department, cost center, and termination data. Termination events flow straight into [offboarding tasks](/layer/offboarding) so departing employees trigger their per-app action plan automatically. Connect any of the three from the **Integrations** page in the dashboard. ## Notion connector [#notion-connector] A new [Notion integration](/layer/integrations/notion) is live in the Layer integrations catalog. Connect a Notion workspace through OAuth and Layer surfaces the workspace itself as a SaaS app and inventories every workspace member as a Layer user, so Notion seats and members flow into [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) alongside the rest of your stack. Workspaces connected without the Notion `read_user` scope still register as a SaaS app — granting the scope unlocks the per-member roster on the next sync. ## Gmail receipt scanner [#gmail-receipt-scanner] A new **Gmail Receipt Scanner** connector now reads vendor receipts directly from a connected Gmail mailbox and turns them into Layer assets. The initial scan covers the trailing 12 months of mail, parses the full email body for vendor, amount, and renewal terms, and adds discovered SaaS subscriptions to your asset inventory automatically — no manual contract upload required for anything that lands in your inbox. Companion support for Microsoft 365 mail is enabled at the same time, so M365 Mail and Gmail receipts both flow into the same [asset inventory](/layer/getting-started) and feed [contracts](/layer/contracts) and [spend management](/layer/spend-management) downstream. ## Asset bundles with one-click assignment [#asset-bundles-with-one-click-assignment] The **Assets → Bundles** page lets you define reusable sets of assets — for example, a "New Hire Bundle" with a laptop, monitor, and peripherals — and assign the whole bundle to a user in one click. Each bundle template carries a per-item monthly cost rollup so you can see the total recurring cost of provisioning the bundle before you assign it, and an assignment record is written for every bundle issued so finance and IT share a single view of who has what. Bundles are scoped per workspace and integrate with the existing [asset inventory](/layer/getting-started) and [offboarding](/layer/offboarding) flows. This is a dated release record. The [current bundle flow](/layer/asset-bundles) matches hardware requirements against existing serialized inventory, reports shortages, and never creates asset records or provisions SaaS licenses. ## Manual asset creation and CSV bulk import [#manual-asset-creation-and-csv-bulk-import] The Assets page now supports two ways to add inventory without waiting for a connector sync: * **Create asset** — a modal for adding a single asset (SaaS app, device, or user-assigned record) by hand, with full status and metadata fields. * **CSV import** — bulk-load up to 1,000 assets per file, with column-level validation and a preview before commit. Use either when onboarding pre-existing inventory that doesn't live in a connected source system, or when you need to record assets from vendors Layer doesn't yet integrate with directly. Assets created either way appear in the inventory immediately and participate in [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) just like discovered assets. ## Sign-in consolidates on Auth0 Universal Login [#sign-in-consolidates-on-auth0-universal-login] The [Layer login and sign-up pages](https://app.axiomlayer.io/login) now route every sign-in through Auth0 Universal Login. Both pages render a single primary action — **Sign in** on `/login` and **Create account** on `/signup` — that hands off to Auth0, where you complete authentication with Google Workspace, Microsoft, or any other identity provider configured on your tenant. After Auth0 confirms the session, Layer mints the matching tenant session and lands you on the dashboard with everything wired up — no second sign-in. The previous in-page email/password form and the standalone **Continue with Google Workspace** button have been retired. Existing accounts — including those originally created with email and password — continue to sign in through Auth0 with the same email address and the corresponding Auth0 credential, and retain all of their organization data, integrations, and history. New accounts continue straight to **Create your workspace** after their first Auth0 sign-in. The `?next=` redirect parameter on `/login` is preserved through the Auth0 round-trip, so deep links into the dashboard still resolve to the originally requested path. See [Getting started](/layer/getting-started). ## Azure connector links resource groups to their subscription [#azure-connector-links-resource-groups-to-their-subscription] The [Azure integration](/layer/integrations/azure) now emits a **HostedOn** relationship from every discovered resource group to its parent subscription, with the resource group's `location` stored as relationship metadata. Existing Azure connections pick up the new edges on their next sync — no reconnection or permission change required. The result is a connected view of how each resource group rolls up to the subscription that owns it, so [access reviews](/layer/access-reviews) and compliance evidence in [Axiom Codex](/codex) can scope role-assignment blast radius down the Azure hierarchy without manually stitching subscriptions to their resource groups. ## GitHub connector now surfaces Copilot seats and per-org members [#github-connector-now-surfaces-copilot-seats-and-per-org-members] The [GitHub integration](/layer/integrations/github) now emits each connected GitHub organization as its own SaaS app, lists every org member as a Layer user with last-active timestamps, and records a Copilot license entry for each provisioned seat on Copilot Business or Enterprise plans. Organizations without Copilot are skipped silently. The result is a more complete picture of GitHub seat utilization in the asset inventory and a direct feed for compliance evidence on developer-tool access. ## Okta connector now maps every user to their assigned apps [#okta-connector-now-maps-every-user-to-their-assigned-apps] The [Okta integration](/layer/integrations/okta) now emits a SaaS app for every Okta-managed application and a per-user assignment for every user→app pairing it discovers, alongside the existing user and group sync. Each assignment records when the user was first granted access, so the inventory surfaces which Okta-managed apps each employee actually has access to, and which assignments haven't been touched. Useful for spotting dormant accounts, rightsizing licenses ahead of an [access review](/layer/access-reviews), and feeding Okta-managed SaaS into [offboarding](/layer/offboarding) automatically. ## Inactive-user flagging on Microsoft 365 / Entra ID [#inactive-user-flagging-on-microsoft-365--entra-id] The [Microsoft 365 integration](/layer/integrations/microsoft-365) now reads Entra ID's `signInActivity.lastSignInDateTime` for every synced user and flags accounts with no interactive sign-in in the trailing 90 days. Inactive users surface in [access reviews](/layer/access-reviews) so you can reclaim or deprovision dormant licenses without manually cross-referencing sign-in logs. ## Inactive-user flagging on Google Workspace [#inactive-user-flagging-on-google-workspace] The [Google Workspace integration](/layer/integrations/google-workspace) now reads each user's last sign-in time from the Admin Reports API and flags accounts with no activity in the trailing 90 days. Dormant Workspace identities surface in [access reviews](/layer/access-reviews) and feed [offboarding](/layer/offboarding) without manually cross-referencing the admin console. Connections that haven't been re-authorized for the new reports scope continue syncing as before; granting **View Reports** on the existing OAuth consent screen unlocks the inactive-user signal automatically. ## Installed app inventory from Jamf, Intune, and Kandji [#installed-app-inventory-from-jamf-intune-and-kandji] The [Jamf](/layer/integrations/jamf), [Intune](/layer/integrations/intune), and Kandji connectors now inventory every application installed across your managed device fleet. Each discovered app appears as a SaaS app in the [integrations](/layer/integrations/overview) inventory, and an **installed on** relationship links each app to the devices it's running on — so you can see at a glance which laptops actually have a given tool, surface unmanaged installs that never went through procurement, and drive deprovisioning from the same view that already tracks device assignment. App inventory ships alongside the existing device sync on each connector with no extra connection step. Intune requires the `DeviceManagementManagedDevices.Read.All` Graph permission to enumerate detected apps; tenants without it continue to sync devices unchanged. ## OAuth grants now appear as SaaS apps [#oauth-grants-now-appear-as-saas-apps] Google Workspace and Microsoft 365 / Entra ID syncs now emit a SaaS app entry for every third-party OAuth application granted access to your tenant, alongside the user, group, and device data they already produced. Shadow OAuth integrations users have authorized — the long tail of "Sign in with Google" and Entra app consents — now show up in the [Apps view](/layer/integrations/overview) automatically, with the granting user attached for follow-up. ## Entra ID OAuth grants link the granting user [#entra-id-oauth-grants-link-the-granting-user] The [Microsoft 365 / Entra ID](/layer/integrations/microsoft-365) connector now records a per-user **Uses** relationship for every third-party OAuth grant it discovers, so each shadow app that lands in the [Apps view](/layer/integrations/overview) is wired directly to the employees who consented to it. Useful for triaging risky OAuth grants — open the app, see exactly who granted access and which scopes were approved, and route follow-up without exporting consent logs by hand. No new permissions are required; the relationships are derived from the same `oauth2PermissionGrants` data the connector already reads. ## Google Workspace OAuth grants link the granting user [#google-workspace-oauth-grants-link-the-granting-user] The [Google Workspace](/layer/integrations/google-workspace) connector now records a per-user **Uses** relationship for every third-party OAuth grant it discovers, matching the Entra ID behavior. Each shadow app surfaced from a `Sign in with Google` consent now lands in the [Apps view](/layer/integrations/overview) wired directly to the employees who authorized it, with the approved scopes attached to the relationship. Open a discovered OAuth app, see the exact list of users who granted access and the scopes each one approved, and route review or revocation without re-running the per-user token enumeration by hand. No new scopes are required — the relationships are derived from the same per-user `admin.directory.user.security` token data the connector already enumerates for app discovery. Existing connections pick up the new relationships automatically on the next sync. ## MDM device assignments link directly to users [#mdm-device-assignments-link-directly-to-users] The JumpCloud MDM and Level.io connectors now emit an **AssignedTo** relationship from each managed device to the user it's assigned to, derived from the assigned-user fields each tenant already returns. Device-to-user links surface in the asset inventory and feed [offboarding](/layer/offboarding) automatically — when an employee leaves, every managed laptop wired to them is queued for reclaim alongside their SaaS access. No new permissions or scopes are required; the relationships are derived from the same device sync the connectors already run, and existing connections pick them up on the next sync. ## OneLogin connector now inventories assigned apps [#onelogin-connector-now-inventories-assigned-apps] The OneLogin connector now emits a SaaS app entry for every application in your OneLogin catalog and a per-user assignment for each user→app pairing it discovers, alongside the existing user roster. Inventory and assignment data flow into the [Apps view](/layer/integrations/overview) and feed [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) so OneLogin-managed seats are visible alongside the rest of your stack. Connections without the **Manage Users** scope continue to sync the catalog without per-user assignments; granting the scope unlocks the assignment data automatically on the next sync. ## Apps page now leads with a four-card stats strip [#apps-page-now-leads-with-a-four-card-stats-strip] The [Apps page](https://app.axiomlayer.io) on the Layer dashboard now opens with a four-card stats strip — **Monthly spend**, **Managed licenses**, **Discovered apps**, and **AI tools** — pinned above the apps table, so the headline numbers for the connected SaaS surface are visible the moment the page loads. The strip rolls up the same data already used downstream in [spend management](/layer/spend-management) and the [integrations](/layer/integrations/overview) inventory, and tracks the active filter so the totals reflect the apps you're actually looking at. ## Seat utilization bars on the Apps table [#seat-utilization-bars-on-the-apps-table] The Apps table on the [Layer dashboard](https://app.axiomlayer.io) now shows a mini progress bar for each app's seat utilization in place of the previous "12 / 50 underused" text. Bars render green when seats are healthily allocated and amber when fewer than half the licensed seats are in active use, so under-utilized SaaS contracts surface at a glance during [access reviews](/layer/access-reviews) and renewal triage. The same bar appears on both the desktop table and the mobile card view. ## Collapsible sidebar with grouped navigation [#collapsible-sidebar-with-grouped-navigation] The [Layer dashboard](https://app.axiomlayer.io) sidebar is now collapsible to an icon-only rail. Toggle it from the footer and the state persists across page reloads. Nav items are also reorganized into four titled sections — **Discover** (Dashboard, Apps, People, Assets, Hardware), **Finance** (Spend, Renewals, Contracts, Licenses), **Operations** (Integrations, AI Usage), and **Account** (Settings, Billing) — so dense product surfaces are easier to scan at a glance, and the missing **Assets**, **Spend**, and **Integrations** items are now first-class entries instead of buried inside other pages. The dashboard layout also clamps to a max width on large monitors so content no longer stretches edge-to-edge. ## ⌘K command palette synced with the sidebar [#k-command-palette-synced-with-the-sidebar] The ⌘K command palette on the [Layer dashboard](https://app.axiomlayer.io) now mirrors the sidebar's four-section structure — **Discover**, **Finance**, **Operations**, **Account** — and picks up every nav item the sidebar surfaces, including AI Usage and the new Assets / Spend / Integrations entries. Jumping to a page from the keyboard now lands you in the same group you'd find it in the sidebar. ## Stats strips on Contracts and Renewals [#stats-strips-on-contracts-and-renewals] The [Contracts](https://app.axiomlayer.io) and [Renewals](https://app.axiomlayer.io) pages now open with a four-card stats strip pinned above the table — **Total Contracts**, **Annual Value**, **Due in 30 Days**, and **Auto-renewal Risk** for Contracts; **Upcoming**, **Due in 30 Days**, **Due 30–60 Days**, and **Auto-renewal count** for Renewals. The headline numbers are visible the moment the page loads, so renewal triage and contract review don't require scrolling into the table to size up the queue. Both pages also pick up the same `PageHeader` treatment as the rest of the dashboard, with action buttons consolidated into the header so the border-bottom separator spans the full width. ## Recharts-backed charts on Spend and Benchmarks [#recharts-backed-charts-on-spend-and-benchmarks] The hand-rolled SVG charts on the [Spend](https://app.axiomlayer.io) detail page and the [Benchmarks](https://app.axiomlayer.io) page have been replaced with interactive recharts components. Spend detail now uses the same `SpendBarChart` as the rest of the dashboard, and Benchmarks ships a vertical grouped bar chart comparing your spend against the peer median per category, with hover tooltips, a legend, and animated entry. Both charts respond to the dashboard's accent color so they stay consistent across themes. ## Loading skeletons across the dashboard [#loading-skeletons-across-the-dashboard] Loading skeletons now match the actual layout of every major dashboard page — **Spend**, **Licenses**, **Contracts**, **AI Usage**, **Benchmarks**, **Assets**, and **Audit**. Each skeleton mirrors its page's `PageHeader`, stats strip, charts, and table rows so navigation feels stable instead of flashing a blank panel before content lands. ## Visual normalization across the dashboard [#visual-normalization-across-the-dashboard] A sweeping polish pass on the [Layer dashboard](https://app.axiomlayer.io). Every card, panel, and container now uses the same `rounded-2xl` corner radius (settings, licenses, contracts, renewals, spend, assets, apps, and people detail views previously rendered slightly tighter corners). Table headers across Contracts, Licenses, Dashboard, Benchmarks, and Spend detail are normalized to `font-semibold`. The `AssetTypeBadge` now shows **SaaS App** correctly (previously rendered "Saas App") and ships explicit labels and color tints for all 17 asset types. Every major page — Integrations, Settings, Search, Licenses, AI Usage, Benchmarks, Assets, AI Usage sub-pages, virtual cards, license sub-pages — now uses the shared `PageHeader` component, with a consistent title → subtitle → border-bottom hierarchy and a `← Back` link on every detail or sub-page. ## Apps and People views populate after sync [#apps-and-people-views-populate-after-sync] The Layer dashboard's **Apps** and **People** views now render the data your connected sources actually return. A workspace-scoping bug was silently zeroing out reads for connected organizations, so freshly synced apps from Google Workspace, Microsoft 365, GitHub, and the rest of the catalog — and employees from connected HRIS and directory sources — appeared as blank views even when sync logs reported records ingested. Reads now resolve against the correct workspace context, and existing connections start populating both views on the next page load. No re-sync required. ## Dashboard widgets render for connected orgs [#dashboard-widgets-render-for-connected-orgs] Patched a production bug where the dashboard's spend, employee-cost, and integration widgets rendered as empty states for orgs that had real data behind them. The widgets — including the **employee count** and per-app cost rollups — now resolve correctly on first load. The same fix repairs the assets page and the employee-costs API, so any surface that depended on the underlying scoping is back to live numbers. ## Platform-initiated ingest no longer rate-limited [#platform-initiated-ingest-no-longer-rate-limited] Per-request rate limits on the [Drift](https://axiomdrift.io) ingest endpoint now trust the platform-supplied client IP, so syncs initiated by the platform itself — health checks, scheduled refreshes, and connection backfills — are no longer throttled when many connected workspaces fire at once. User-driven ingest from third-party forwarders continues to be rate-limited per-IP exactly as before. ## Connector sync registers every supported source [#connector-sync-registers-every-supported-source] Adding a connector to a workspace now succeeds for every source in the catalog. A registration step had been skipped for some new connectors, surfacing as an "unsupported source" error on first sync — most visibly for **Microsoft Entra ID**, which is now correctly aliased to its underlying directory connector. Existing connections are unaffected; new connections complete their first sync without manual retry. ## Faster cockpit row sampling [#faster-cockpit-row-sampling] Sample-row lookups on the Layer cockpit now run their candidate queries in parallel instead of sequentially, cutting a noticeable delay on tables where the canonical column varied between tenants. No user-facing changes beyond the speedup. ## Sentry Replay disabled on authenticated routes [#sentry-replay-disabled-on-authenticated-routes] [Sentry Session Replay](https://sentry.io) no longer records on the authenticated `/dashboard` and `/settings` surfaces in the Layer dashboard, and any in-flight replay stops on client-side route transitions away from a replay-eligible page. Tenant data never enters a replay buffer; production exception reporting and stack traces are unchanged. ## Marketing and login pages recover cleanly from server errors [#marketing-and-login-pages-recover-cleanly-from-server-errors] The public marketing surface and the sign-in / sign-up pages on the [Layer dashboard](https://app.axiomlayer.io) now render a friendly recovery screen with a **Try again** button when an unexpected server error occurs, instead of leaving the browser stuck on a blank page or a closed connection. The dashboard, billing, and integration surfaces — which already had their own error boundaries — are unaffected. ## Platform reel renders again on axiomancer.io [#platform-reel-renders-again-on-axiomancerio] The scroll-driven platform reveal on [axiomancer.io](https://axiomancer.io) is visible again. A page-level overflow setting was preventing the sticky scroll behavior from engaging on descendant elements, leaving a tall blank section where the product reel should have been. Visitors now see the full scroll-driven reveal of the product lineup as intended. ## Commodity prices, river levels, disruption signals, and Brazil COMEX ingestion repaired [#commodity-prices-river-levels-disruption-signals-and-brazil-comex-ingestion-repaired] Four Overwatch ingestion sources that had been silently writing zero records are back to live updates: * **[Commodity prices](/overwatch/api/market-data#get-apiv1commodity-prices)** now fetch from the [FRED](https://fred.stlouisfed.org/) API (IMF commodity series) instead of the retired World Bank CSV endpoint. Wheat, corn, soybeans, crude oil (Brent and WTI), coal, US natural gas, and iron ore prices resume landing on the weekly Monday 06:00 UTC cron, and the underlying benchmark series — the IMF Primary Commodity Price System — is unchanged, so historical comparisons remain valid. * **[River levels](/overwatch/api/river-levels)** now write port weather rows against the current `port_weather` schema (the previous build was stuck on a stale revision that referenced retired `conditions`, `wind_speed_mph`, and `raw_data` columns and rejected every insert). Mississippi, Ohio, Illinois, and Columbia gauge readings — plus the Houston entry — flow into the public endpoint and into derived port detail and congestion views again. * **[Disruption signals](/overwatch/api/disruptions)** are sized to fit GDELT's roughly 10-requests-per-day rate limit by trimming the per-run query set from six to three and dropping the cron from every six hours to once daily. The endpoint shape is unchanged; the trade-off is that the freshest disruption headlines now refresh on a daily cadence instead of a four-times-daily one. * **Brazil COMEX** ingestion, which had been deployed without a cron entry, is now scheduled monthly on the 8th at 06:00 UTC, so Brazilian foreign trade snapshots flow into the dataset on the regular monthly cycle expected by downstream trade-flow consumers. No action is required on your part — existing API keys, query parameters, and response shapes are unchanged. Records resume on the next scheduled run for each source, and a one-time backfill is closing the gap on the silent-failure window. ## Hourly COLREGS compliance scoring is running again [#hourly-colregs-compliance-scoring-is-running-again] The hourly [COLREGS compliance scoring](/overwatch/methodology/encounter-extraction#colregs-compliance-scoring) pass that runs at `:17` past every hour is back on schedule. As the underlying [pairwise encounter](/overwatch/methodology/encounter-extraction) table grew, the scoring pass had been scanning a full 24-hour lookback against an unindexed timestamp column on every run and timing out before any rows were written, leaving the `colregs_encounters` table frozen at 451 rows for roughly 21 hours. The lookback is now narrowed to the trailing three hours — still a 3-run safety buffer for an hourly cron — and the filter is switched onto the indexed encounter-start column, so the pass completes well inside the statement-timeout window. A companion index covers the legacy CPA-timestamp call path used by manual backfill, so backfill drivers also stop tripping the timeout. Compliance deficits resume landing on schedule from the next `:17` run forward, and a one-time backfill is catching up the 21-hour gap. ## GitHub teams, members, and repository governance [#github-teams-members-and-repository-governance] The [GitHub integration](/layer/integrations/github) now emits a **Team** asset for every team in each connected GitHub organization, along with two new relationship types that map the real access path through teams: * **MemberOf** — every team member is linked to the team they belong to. * **GovernedBy** — every repository a team is granted access to is linked back to the team, with the team's permission level (`pull`, `push`, `admin`, etc.) stored on the relationship. The result is a complete picture of *which engineers are on which teams, and which repos those teams govern* — so [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) can revoke team-derived repository access in a single step instead of hunting through org-wide permissions. No reconnection needed: existing GitHub installations pick up teams and team-driven access on their next sync, as long as the Axiom GitHub App was granted **Members: Read** and **Metadata: Read** at install time. ## Collapsible sidebar and grouped navigation [#collapsible-sidebar-and-grouped-navigation] The [Layer dashboard](https://app.axiomlayer.io) sidebar now collapses to an icon-only rail. Click the toggle in the sidebar footer to switch between the full 256px sidebar and a compact 60px rail; the choice persists across page loads, so the sidebar opens in the same state on your next visit. In collapsed mode, hovering an icon shows the item name as a native tooltip. Nav items are now organized into four sections — **Discover** (Apps, People, Assets, Hardware), **Finance** (Spend, Renewals), **Operations** (Integrations, AI Usage, Audit log), and **Account** (Settings) — and three pages that already shipped but were missing from the nav are now linked directly: [Assets](/layer/getting-started), [Spend](/layer/spend-management), and [Integrations](/layer/integrations/overview). Section labels collapse to thin dividers in icon mode. The main content area is now constrained to a max width on large monitors so dashboard pages stay readable instead of stretching edge-to-edge, and page headers gained a subtle bottom border plus an optional badge slot next to the title. # Week of May 3–9, 2026 (/changelog/2026-05-09-weekly) This is a historical release record. Launch-supported chokepoint confirmation is currently AIS-only; Sentinel catalog coverage does not detect vessels or confirm transits. See the [current methodology](/overwatch/methodology/chokepoint-transits). ## This week at a glance [#this-week-at-a-glance] A focused week on Overwatch's collision-avoidance analytics — a new COLREGS Rule 17 deviation flag now lights up on [pairwise encounters](/overwatch/methodology/encounter-extraction) where a vessel with high stand-on probability makes a meaningful course change during the risk window, surfacing maneuvers that, under the rules of the road, are only authorized when the give-way side has clearly failed to keep clear. A new monthly NOAA-backed per-port water density refresh feeds directly into the [hydrostatic cargo validation](/overwatch/methodology/cargo-validation) pipeline so freshwater-vs-saltwater displacement corrections stay accurate per port. This dated recap reported restored SAR chokepoint confirmation; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary), and the [Sentinel endpoint](/overwatch/api/sar-coverage) now documents catalog metadata only. The release also reported restored AIS [downsampling](/overwatch/data-retention), hardened the [pairwise encounter](/overwatch/methodology/encounter-extraction) ingestion path so growing encounter volume no longer trips the database statement timeout, and brought [course-alteration anomaly](/overwatch/api/risk) detection live in production for the first time — the detector had been wired into a path the production worker never executed, so the unified alerts inbox and the matching [Alert Rule Builder](/overwatch/api/alerts) template had been silently empty until this week. A production sweep tightened webhook URL validation on [alert channels](/overwatch/api/alerts), retired stale crons pointing at deleted Edge Functions, taught the course-alteration worker to raise its own `worker_inactive` alert when input dries up, and stopped the [Codex envelope coverage dashboard](/codex/envelope-coverage) refresh from timing out on tables above one million rows. A second sweep repaired four dead-upstream ingestion paths — [commodity prices](/overwatch/api/market-data) (now sourced from the FRED API after the previous URL went dark March 30), [disruption signals](/overwatch/api/disruptions) (rate-limit-aware GDELT fetch on a daily cron), [river levels](/overwatch/api/river-levels) (schema drift fixed so Mississippi/Ohio/Illinois/Columbia/Houston gauges resume populating), and [Brazil COMEX](/overwatch/api/trade-flows) (a missing monthly cron is now scheduled). Layer also picked up a sizeable feature lift on the dashboard — asset management with manual entry, CSV import (up to 1,000 rows), and reusable cost-rolled-up **bundles** for one-click provisioning to a user; three new SaaS-discovery connectors (**Microsoft Teams**, **[Atlassian](/layer/integrations/atlassian)**, and **Workday HRIS**, the platform's first dedicated HRIS source); a new **Gmail Receipt Scanner** so SaaS receipts surface as Layer assets via the standard sync route; an upgraded [GitHub](/layer/integrations/github) connector that now emits per-org-member users with last-active timestamps and a separate **Copilot License** asset per active assignment; and SaaS apps automatically surfaced on the [integrations](/layer/integrations/overview) inventory from third-party OAuth grants detected by the [Google Workspace](/layer/integrations/google-workspace) and Microsoft Entra ID syncs. Layer also shipped a security hardening pass on the dashboard's Content-Security-Policy, rolled back the HSTS `preload` directive on the dashboard and Drift until subdomain HTTPS verification is complete, polished dashboard tables so nested controls and out-of-range pagination no longer misbehave, hardened the public API proxy and the post-login `next` redirect against open-redirect and prefix-match payloads, gated [Plans and billing](/layer/billing) endpoints behind admin and owner roles on both Layer and Drift, synced Drift team invites and role changes into trusted Supabase `app_metadata` so server-side authorization reads from a single tamper-resistant source, repaired Drift's **Load sample data** action so demo workspaces seed cleanly on first click, scrubbed PII from production Sentry error reports across both apps, repaired the dashboard login page's third-party sign-in entrypoint to run the Supabase Google Workspace OAuth handoff, required provider-authenticated webhooks before committing virtual-card balances, and shipped a marketing-page mobile fix. Locus extended the same security-header pass across the authenticated app, restored POI collection to its 6-hourly cadence, scheduled APRS backfills for three zero-coverage tables, picked up a PWA manifest plus mobile and SEO polish, and HTML-escaped place names in free-report confirmation emails. Overwatch and Axiomancer landing surfaces picked up branded OpenGraph cards, `robots.txt`, and `sitemap.xml`, and Axiomancer rolled back a mid-week mobile-optimization pass that had regressed the desktop hero, engine, footer, and platform-reel layouts. Drift tightened its production CSP and IP-attribution path. Locus and Codex repaired the **RouteShift** entry in the cross-product navigation bar so it points to the live `routeshift.io` domain. ### New features [#new-features] * **Overwatch**: Rule 17 deviation flags on [vessel-to-vessel encounters](/overwatch/methodology/encounter-extraction). Each [pairwise encounter](/overwatch/api/risk) now carries per-vessel `max_course_change_deg` and `rule17_deviation` fields. The flag fires on a vessel whose mean stand-on probability across the encounter window is at least 0.6 *and* whose maximum single-step course change during the window is 10° or more — the geometry of a stand-on vessel taking unilateral evasive action that COLREGS Rule 17 only authorizes when the give-way vessel has clearly failed to keep clear. Useful for surfacing unannounced maneuvers, attributing close-quarters action to the correct party, and cueing forensic review on encounters where the rule-of-the-road expectation and observed behavior diverge. The companion course-change magnitude is recorded directly on the encounter row so analysts can verify the trigger without replaying AIS. * **Overwatch**: Per-port surface water density now refreshes monthly into the [cargo validation](/overwatch/methodology/cargo-validation) pipeline. US ports use NOAA CO-OPS real-time temperature with climatological salinity (confirmed coverage at New Orleans, Houston, Baltimore, Norfolk, and Los Angeles), and a country- and water-body-aware climatology covers international ports — including extreme overrides for Arctic, Persian Gulf, Red Sea, Black Sea, and Hormuz waters. Density is computed via the UNESCO-80 seawater equation of state, stored at H3 resolution 8 with the underlying source identifier, and used directly in the displacement step of [hydrostatic cargo estimates](/overwatch/methodology/cargo-validation#water-density-sources) so freshwater-vs-saltwater corrections are accurate per port without manual tuning. * **Layer**: Asset management ships in the [Layer dashboard](https://app.axiomlayer.io). Create assets manually, bulk-import up to 1,000 rows from CSV, and group recurring provisioning into reusable **asset bundles** with a cost rollup and one-click assignment to a user. This is a dated release record; the [current bundle flow](/layer/asset-bundles) matches repeatable hardware kits against existing serialized inventory and does not create assets or provision SaaS licenses. * **Layer**: Four new SaaS-discovery connectors land on the [integrations catalog](/layer/integrations/overview) — **Microsoft Teams** discovers Teams itself as a SaaS app and surfaces per-user activity from team membership, **[Atlassian](/layer/integrations/atlassian)** emits a separate SaaS app per Jira / Confluence / etc. product with per-user last-active timestamps, **Workday HRIS** ingests paginated workers with department, cost center, and termination dates (Layer's first dedicated HRIS source for headcount and offboarding signals), and **[Notion](/layer/integrations/notion)** emits the connected Notion workspace as a SaaS app and inventories every workspace member as a Layer user via OAuth, so Notion seats roll into access reviews and offboarding alongside the rest of the stack. * **Layer**: **Gmail Receipt Scanner** is now available for Layer. Receipts surfaced from Gmail and Microsoft 365 mail flow into the dashboard as Layer assets via the standard sync route, with a 12-month initial scan window so a fresh connection backfills the last year of SaaS receipts on first sync. * **Layer**: The [GitHub](/layer/integrations/github) connector now emits a User per organization member alongside the SaaS app, with last-active timestamps from the org audit log and a separate **Copilot License** asset per active assignment so Copilot seats appear directly in license inventory and access reviews. * **Layer**: The [GitHub](/layer/integrations/github) connector now also emits a Team asset per GitHub team within each connected org, alongside membership and repository relationships — every team member surfaces with a **MemberOf** relationship to its team, and every repository the team has access to surfaces with a **GovernedBy** relationship. Useful for spotting overprovisioned teams during [access reviews](/layer/access-reviews), tracing repository access back to the team that grants it, and feeding [offboarding](/layer/offboarding) when a departing employee belongs to multiple teams. Sub-fetches are fail-safe per team, so a single inaccessible team no longer blocks the rest of the sync. * **Layer**: The [JumpCloud](/layer/integrations/overview) connector now emits a SaaS app per distinct application surfaced in the trailing 30 days of SSO events, a **Uses** relationship per user→app pair (deduped, with the most recent timestamp preserved), and **MemberOf** relationships for every user group it discovers. Surfaces JumpCloud-managed seats in the [integrations](/layer/integrations/overview) inventory and feeds [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) alongside Okta and OneLogin, with no additional API calls beyond the existing user and event fetch. * **Layer**: The [Google Workspace](/layer/integrations/google-workspace) and Microsoft Entra ID connectors now emit a SaaS app per third-party OAuth grant detected during sync, so apps connected with "Sign in with Google" or "Sign in with Microsoft" show up in the [integrations](/layer/integrations/overview) inventory automatically without a separate connector for each one. Both sides also record a per-user **Uses** relationship for every grant — with the approved scopes attached on the Google Workspace side — so each shadow app surfaces with the employees who actually consented to it attached for follow-up. * **Layer**: The OneLogin connector now emits a SaaS app per application in the OneLogin catalog and a per-user assignment for every user→app pairing it discovers, so OneLogin-managed seats roll into the [integrations](/layer/integrations/overview) inventory and feed [access reviews](/layer/access-reviews) alongside Okta. Connections without the **Manage Users** scope continue to sync the catalog; granting the scope unlocks the assignment data automatically. * **Layer**: The [Okta](/layer/integrations/okta) connector now emits a SaaS app per Okta-managed application and a per-user assignment for every user→app pairing it discovers, with `assigned_at` timestamps. Surfaces which Okta-managed apps each employee actually has access to in the [asset inventory](https://app.axiomlayer.io), so dormant accounts and oversized license footprints show up directly in [access reviews](/layer/access-reviews) without manual cross-referencing. * **Layer**: The JumpCloud connector now emits a SaaS app for every distinct application discovered in the trailing 30 days of SSO events, with a per-user **Uses** relationship for every employee who actually signed in to that app. User-group membership is also inventoried as a per-user **MemberOf** relationship, so JumpCloud-managed apps and group memberships flow into the [integrations](/layer/integrations/overview) inventory and feed [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) without a separate import. No new permissions are required — the depth comes from data the connector was already fetching. * **Layer**: The [Jamf](/layer/integrations/jamf), [Intune](/layer/integrations/intune), and Kandji connectors now inventory every application installed across the managed device fleet. Each discovered app lands as a SaaS app in the [integrations](/layer/integrations/overview) inventory with an **installed on** relationship to the devices running it, so unmanaged or out-of-procurement installs surface alongside the device record and feed [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) automatically. Jamf and Kandji pick up the new inventory with no permission change; Intune requires the `DeviceManagementManagedDevices.Read.All` Graph permission to enumerate detected apps and continues syncing devices unchanged when it isn't granted. * **Layer**: The JumpCloud MDM and Level.io connectors now emit an **AssignedTo** relationship from each managed device to its assigned user, so every laptop or workstation surfaced from those connectors lands in the [integrations](/layer/integrations/overview) inventory wired directly to the employee it's issued to. Useful for spotting devices whose assigned user has left, attributing installed-app footprints to the right person during [access reviews](/layer/access-reviews), and fully driving device collection from the same view that already tracks app and license assignment during [offboarding](/layer/offboarding). No new permissions are required — the assignment is derived from data both connectors were already fetching. ### Updates [#updates] * **Layer**: Sign-in and signup on the [Layer dashboard](https://app.axiomlayer.io) now run through Auth0 Universal Login. The [`/login`](https://app.axiomlayer.io/login) and [`/signup`](https://app.axiomlayer.io/signup) pages are now single-button handoffs to the Auth0-hosted page; the **Continue with Google Workspace** button takes the same Auth0 path and then mints a Supabase session in the background, so a single click lands you on the dashboard with both sessions established. The standalone email/password form on the Layer login page has been retired in favor of the Auth0 surface — credentials are entered on Auth0, never on the Layer dashboard. Post-login `next` redirects are preserved end-to-end. Existing accounts retain all of their organization data, integrations, and history. See [Getting started](/layer/getting-started). * **Layer**: Tables across the [Layer dashboard](https://app.axiomlayer.io) — integrations, spend, access reviews, contracts, and friends — now feel right on the edges they used to bite. Clicking a checkbox, button, link, menu, dropdown, or other interactive control nested inside a row no longer also fires the row's primary navigation, so opening a row menu or selecting a row's checkbox stops short of also drilling into the row. Paginated tables also clamp to the last available page when filters or data changes would otherwise leave you stranded on an empty out-of-range page, so toggling a filter on a deep page lands you on real rows instead of a blank table. * **Layer**: Dashboard polish wave on [app.axiomlayer.io](https://app.axiomlayer.io). The sidebar is now collapsible to icon-only with persisted state and items grouped into **Discover** / **Finance** / **Operations** / **Account**, the dashboard layout clamps to a max width on large monitors, and missing **Assets**, **Spend**, and **Integrations** entries are now first-class. Every major page — Integrations, Settings, Search, Licenses, AI Usage, Benchmarks, Assets, virtual cards, license and AI usage sub-pages — now ships the shared `PageHeader` component with a consistent title → subtitle → border-bottom hierarchy and `← Back` links on detail pages. Apps, Contracts, and Renewals open with four-card stats strips above the table, hand-rolled SVG charts on the Spend detail and Benchmarks pages have been replaced with recharts grouped-bar components with hover tooltips and legends, and loading skeletons matching the actual page layout now ship on Spend, Licenses, Contracts, AI Usage, Benchmarks, Assets, and Audit. The ⌘K command palette is synced to the new sidebar groups, the `AssetTypeBadge` now shows **SaaS App** correctly with labels and tints for all 17 asset types, table headers normalize to `font-semibold`, and every card and panel uses the same `rounded-2xl` corner radius across the dashboard. * **Overwatch**: Tightened security headers on [axiomoverwatch.io](https://axiomoverwatch.io) and tightened authentication on the internal cron endpoints that drive ingestion, archival, alert delivery, and Locus portfolio refresh. No user-facing behavior changes; browsers benefit from the stricter Content-Security-Policy and related headers automatically. * **Overwatch / Axiomancer**: [axiomoverwatch.io](https://axiomoverwatch.io) and [axiomancer.io](https://axiomancer.io) both received a professionalization pass — branded OpenGraph and Twitter `summary_large_image` social previews, a `robots.txt` and `sitemap.xml` at site root, refreshed alt text on marketing imagery, and analytics gating so PostHog and Amplitude only initialize on consent. Links unfurl with full-bleed branded previews on Slack, X, LinkedIn, and any embed-friendly surface, and search engines can index the public marketing surface without relying on link traversal. * **Axiomancer**: Restored the desktop layout on [axiomancer.io](https://axiomancer.io). A mid-week mobile-optimization pass to the hero, engine, footer, and platform reel had collapsed several desktop sections to single-column and skipped frames on narrow screens; those components have been rolled back to the pre-mobile-pass desktop layout. The legal page polish, **RouteShift** link fix, navbar improvements, source ticker, and static hero poster from the same week are retained. Mobile-specific layout refinements will return on a separate pass that doesn't regress desktop. * **Overwatch**: The public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint now preserves and returns underlying error details when an upstream component fails, instead of collapsing to a generic 500. API consumers building live maps and dashboards on top of the endpoint can now distinguish between transient upstream issues and request-side problems without retrying blindly. * **Locus**: Locus admin authorization on the [authenticated API](/locus/api/overview) and `/admin/*` routes now resolves through stable identity claims first and only falls back to the email allowlist for compatibility. Two new environment variables — `ADMIN_USER_IDS` (immutable Supabase user UUIDs) and `ADMIN_ROLE_CLAIMS` (role names on `app_metadata` or `user_metadata`) — are checked before `ADMIN_EMAILS`, so admin access survives an email change at your identity provider. Existing `ADMIN_EMAILS` configurations keep working unchanged; legacy email-based grants now log a per-request warning naming the user ID so you can audit who's still relying on them before you remove the variable. Only operators of self-hosted and preview deployments need to act. * **Overwatch**: Admin auth on the Overwatch sensitive-endpoint surface — webhooks, key management, and the rest of the admin API — now resolves through least-privilege identity paths first and only falls back to the legacy shared admin key for compatibility. Three new environment variables are checked before `ADMIN_API_KEY`: `ADMIN_USER_IDS` (immutable Supabase user UUIDs), `ADMIN_ROLE_CLAIMS` (role names matched against trusted Supabase `app_metadata` only — `user_metadata` is excluded because it's commonly user-writable), and `ADMIN_MACHINE_KEYS` (scoped per-automation secrets), so a single leaked admin key is no longer a fleet-wide compromise. The previous per-IP rate limit and constant-time hash compare are unchanged, and a leaked-secret incident can now be contained by rotating one row in `ADMIN_MACHINE_KEYS` instead of the shared `ADMIN_API_KEY`. Existing `ADMIN_API_KEY` configurations keep working unchanged; only operators issuing admin requests need to migrate. * **Locus**: [locus.axiomancer.io](https://locus.axiomancer.io) received the same professionalization pass that landed on Overwatch and Axiomancer — refreshed alt text and tap-target sizing on the marketing surface (mobile links and the **Get Access** button now meet the 44 px minimum), a PWA manifest with branded icon and theme color so the site installs cleanly on mobile home screens, and analytics gating that suppresses PostHog session recording outside of production and on `/admin` and `/settings` routes. The Locus marketing pages also now declare `neighborhood analytics` and `demographic data` as additional keywords for discovery. No user-facing behavior changes for authenticated workflows — the Explorer, dashboard, and API surface are unchanged. * **Layer**: The Microsoft Entra ID connector now reads each user's `signInActivity.lastSignInDateTime` and flags accounts inactive for 90+ days. Useful for surfacing dormant identities ahead of an [access review](/layer/access-reviews) or scheduled offboarding without exporting the directory by hand. * **Layer**: The [Google Workspace](/layer/integrations/google-workspace) connector picks up the same dormant-user signal — last sign-in time is read from the Admin Reports API on every sync, and accounts with no activity in the trailing 90 days now flag as inactive in the [access review](/layer/access-reviews) surface. Connections without the new reports scope continue syncing without error; granting **View Reports** on the existing OAuth consent screen unlocks the signal automatically. ### Fixes [#fixes] * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: This release reported SAR chokepoint confirmation back on cadence. The current [Sentinel endpoint](/overwatch/api/sar-coverage) exposes scene catalog metadata only and does not detect vessels, confirm transits, or maintain dark-transit flags. * **Overwatch**: AIS [downsampling](/overwatch/data-retention) is processing positions again, so the live database's tiered retention surface stays within its 90-day window without a backlog. Recent positions remain at full resolution, older positions thin out per the [retention windows](/overwatch/data-retention#retention-windows), and anything older than 90 days continues to live in the cold archive. * **Overwatch**: [Pairwise encounter](/overwatch/methodology/encounter-extraction) ingestion is durable against table-size-driven timeouts. As the encounter table grew, batched upserts began exceeding the API tier's statement timeout and silently killing the hourly run, producing gaps in the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) feeds. Writes now flow through a hardened bulk-upsert path that isn't subject to the API statement-timeout cap, so encounter geometry — CPA, TCPA, range, closing speed, and COLREGS posteriors — keeps landing on schedule as the table continues to grow. Backfill of the gap window is in progress. * **Overwatch**: Hourly [COLREGS compliance scoring](/overwatch/methodology/encounter-extraction#colregs-compliance-scoring) is running again. The `:17`-past-the-hour scoring pass had been timing out on every run as the underlying encounter table grew — the lookback window was scanning a full day of pairwise encounters against an unindexed timestamp column, leaving the `colregs_encounters` table frozen at 451 rows for roughly 21 hours. The hourly window is now narrowed to the trailing three hours (still a 3-run safety buffer), filtering switched onto the indexed encounter-start column, and a backfill index added for the legacy CPA-timestamp call path. Compliance deficits resume landing on schedule from the next `:17` run forward, with a one-time backfill catching up the 21-hour gap. * **Overwatch**: Cleared roughly 7,800 [vessel enrichment](/overwatch/api/vessels) records that were permanently stuck in the pending queue — vessels whose Equasis profile requires JavaScript to render, plus a handful of malformed IMO numbers that could never resolve. The pending queue dropped from about 22,700 to about 14,800, so enrichment freshness on the remaining backlog improves immediately. Equasis-blocked vessels will pick up automatically once the JS-capable enrichment path ships. * **Overwatch**: Retryable failed [vessel enrichment](/overwatch/api/vessels) queue rows that hadn't exhausted their attempt budget are now reset back to pending automatically, so transient Equasis errors no longer leave otherwise-resolvable vessels parked in the failed bucket. * **Codex**: The [envelope coverage dashboard](/codex/envelope-coverage) refresh no longer times out on very large tables. Tables estimated above 1M rows — primarily `ais_positions` — are now sized from the live row-count statistic rather than an exact `COUNT(*)` scan, so the nightly refresh completes cleanly and per-table compliance percentages stay current. Coverage numbers for smaller tables are unchanged. * **Overwatch**: The course-alteration worker is now self-observable. A new monitor checks for fresh `course_alteration` events every hour and raises a `worker_inactive` alert if none have landed in the trailing 7 days, instead of silently leaving the [Ghost Vessels](/overwatch/api/alerts) inference cron with no input. Alerts auto-resolve as soon as events resume. * **Overwatch**: [Course-alteration anomaly](/overwatch/api/risk) detection is now actually running in production. The detector that emits `course_alteration` events when an underway vessel turns 45° or more off its 6-hour mean heading was wired into a path the production worker never executed, so no events had ever landed in the live [vessel risk](/overwatch/api/risk) feed or the [unified alerts inbox](/overwatch/api/alerts). Detection now runs on every AIS tick on the production worker, with each emit logged at the database layer for observability and a `course_alterations_detected` counter exposed in the worker's heartbeat. Roughly 1,300 vessels per run qualify under the existing 45° / 10-km-from-port thresholds, so course-alteration events, the matching [Alert Rule Builder](/overwatch/api/alerts) template, and the `worker_inactive` self-observability monitor all start producing real signal from the next worker run forward. No backfill — this is forward-only from the fix. * **Overwatch**: Hardened webhook URL validation on [alert channels](/overwatch/api/alerts) — only `https://` destinations on the public internet are accepted, with explicit rejection of internal hostnames, link-local ranges, and other non-routable addresses. Existing webhook subscriptions are unaffected; new and updated subscriptions return a clear error message when an invalid URL is submitted instead of silently accepting it. * **Overwatch**: Production sweep retired stale `pg_cron` schedules invoking deleted Edge Functions and added a reusable detector so future drift surfaces immediately instead of failing silently. The MPO TIP scout now triages no-op upserts against the live target-table count, so swallowed write failures (records fetched, zero upserted, empty target) raise a `silent_upsert_failure` alert instead of looking like an idempotent run. * **Layer**: The [virtual-card](/layer/spend-management) authorization endpoint now requires provider authentication before it will commit a balance change. Dashboard and session-based callers can still evaluate an authorization against the configured spend limit, but the response returns `committed: false` and the running spend total is left untouched — only the card provider (currently Stripe Issuing) can drive a real commit by presenting the shared `x-virtual-card-provider-secret` header on the webhook callback. Closes a path where an authenticated dashboard user could move the cumulative spend total without a provider-side authorization actually clearing. Existing webhook subscriptions, per-vendor spend caps, limit windows, and the [audit log](/layer/audit-log) entries on virtual-card events are unaffected. * **Layer**: Tightened the production Content-Security-Policy on the [Layer dashboard](https://app.axiomlayer.io) — `'unsafe-eval'` is no longer permitted in `script-src` outside local development. `'unsafe-inline'` is retained in production so Next.js App Router hydration and RSC bootstrap scripts continue to run; without it, dashboard pages render as static HTML and client components — including the **Continue with Google Workspace** button — never hydrate. `'unsafe-eval'` stays scoped to development builds so the local workflow keeps working, while production responses now serve the stricter policy on every route. Existing [integrations](/layer/integrations/overview), [billing](/layer/billing), and embedded video continue to work unchanged. * **Layer**: Rolled back the `preload` directive on the `Strict-Transport-Security` response header for the [Layer dashboard](https://app.axiomlayer.io) and the Rogue Stack app, while keeping `max-age=63072000; includeSubDomains` in place. HTTPS-only enforcement and subdomain coverage are unchanged; preload-list submission moves to an explicit rollout decision once every subdomain has been verified to serve HTTPS, so a misconfigured subdomain can't get pinned into the browser preload list. * **Layer**: The cross-product marquee on the [Layer marketing site](https://axiomlayer.io) no longer overflows the viewport on mobile — the row now stays on-screen and stops introducing horizontal scroll on small breakpoints. * **Layer**: Sign-in on the [Layer login page](https://app.axiomlayer.io/login) and signup on [`/signup`](https://app.axiomlayer.io/signup) now hand off to Auth0 Universal Login. The **Continue with Google Workspace** button routes through Auth0 first and then mints a Supabase session in the background, so a single click lands you on the dashboard with both sessions already established. The standalone email/password form has been retired in favor of the same Auth0-hosted page — credentials are entered on Auth0, never on the Layer dashboard surface — and the post-login `next` redirect is preserved end-to-end. Existing dashboard data, integrations, and history are untouched. See [Getting started](/layer/getting-started). * **Layer**: The post-login `next` redirect on the dashboard sign-in page and the Supabase OAuth callback now decodes the parameter before validating it and rejects anything that isn't a same-origin path. Encoded protocol-relative payloads (for example `%2F%2Fexample.com`), backslash-prefixed forms, and control characters all fall back to `/dashboard` instead of bouncing the browser to an attacker-controlled destination. The shared helper is reused by the email/password sign-in path, the **Continue with Google Workspace** button, and the Supabase OAuth callback, so all three flows enforce the same allowlist. * **Layer**: The public API surface on the [Layer dashboard](https://app.axiomlayer.io) now only matches a request when the path is an exact declared prefix or a child path beneath it, instead of any path that happens to share the same opening characters. Requests that previously slipped through on a coincidental string match — for example, a path that began with the same letters as a public API prefix but was a sibling rather than a child — now fall through to the authenticated dashboard surface as intended. Existing endpoints under [`/api/mcp`](/layer/mcp-server), the [discovery extension](/layer/browser-extension), and the rest of the public surface continue to work unchanged. * **Drift**: Tightened the production Content-Security-Policy on [Drift](https://axiomdrift.io) — `'unsafe-inline'` and `'unsafe-eval'` are no longer permitted in `script-src` outside local development, `frame-src` is now `'none'` so the dashboard cannot embed any third-party iframes, and `base-uri`, `object-src`, and `frame-ancestors` are also locked down by default. No user-facing behavior changes; the analytics, billing, and provider integrations powering shadow-IT discovery continue to work unchanged, and browsers benefit from the stricter policy automatically. * **Drift**: Per-IP rate limits on the [Drift](https://axiomdrift.io) ingest webhook, manual connection creation, and sync endpoints now key on the trusted platform-supplied client IP instead of the raw `X-Forwarded-For` header, so a spoofed forwarding header can no longer be used to evade per-IP throttling. No action is required on your part; legitimate forwarders are unaffected. * **Layer**: Connection connect and disconnect events on the [integrations page](/layer/integrations/overview) now record the trusted platform-supplied client IP in the [audit log](/layer/audit-log) instead of the raw `X-Forwarded-For` header, so admins reviewing audit entries see an IP that can't be spoofed by a forwarded-header rewrite. Existing audit entries are unaffected; new entries pick up the hardened attribution automatically. * **Locus**: Tightened the production security headers on [locus.axiomancer.io](https://locus.axiomancer.io). Responses now ship a strict Content-Security-Policy with explicit allowlists for the third-party services Locus actually uses (Mapbox, Stripe, Supabase, Mux, Sentry, PostHog, Intercom, Mixpanel, Amplitude), a restrictive Permissions-Policy that disables sensors, camera, microphone, geolocation, payment, and other powerful APIs by default, and the standard `X-Content-Type-Options`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin` headers. No user-facing behavior changes; browsers benefit from the stricter policy automatically. * **Locus**: POI ingestion is back on its 6-hourly cadence. The `collect-pois` and `collect-pois-premium` crons that populate `poi_snapshots` had drifted onto a once-a-year schedule, leaving the **Nearby POIs** rail in the [Explorer](/locus/explorer), the [`GET /api/pois`](/locus/api/location-data) endpoint, and the POI counts in [`GET /api/enrich`](/locus/api/enrichment) and the [discovery and intelligence](/locus/api/discovery-and-intelligence) endpoints up to 35+ days stale. Both crons now run at 00:00, 06:00, 12:00, and 18:00 UTC daily, restoring the documented `<7 days` POI freshness window. Backfill of the gap window is in progress. * **Locus**: POI enrichment from Yelp and Google Places is producing rows again. The Yelp business search endpoint had been returning errors for every request after an upstream deprecation, and Google Places `nearbysearch` had been denying every request for keys issued after the March 2025 platform cutoff — together leaving the **Nearby POIs** rail in the [Explorer](/locus/explorer), the [`GET /api/pois`](/locus/api/location-data) feed, and the POI counts in [`GET /api/enrich`](/locus/api/enrichment) and the [discovery and intelligence](/locus/api/discovery-and-intelligence) endpoints empty since roughly April 1. The Yelp client now reads from the GraphQL surface on the same API key and daily cap, and Google Places is migrated to the v1 nearby-search endpoint with the new authentication header and response schema. No configuration changes are required; new POI snapshots resume on the next scheduled run, and backfill of the gap window is in progress. * **Locus / Codex**: The three Locus catalog tables still showing 0% APRS envelope coverage on the [envelope coverage dashboard](/codex/envelope-coverage) — `uscis_h1b_employers`, `usda_nass_county_crops`, and `muckrock_foia_requests` — now have nightly backfill jobs scheduled in the 03:30–03:40 UTC low-traffic window. Coverage on these tables will climb toward 100% over the next several nightly cycles, after which they'll join the rest of the Locus catalog in the [`aprs.civic`, `aprs.commodity`, and `aprs.permits`](/locus/data-standards) profile rosters with full envelope-driven joinability and incremental sync. * **Locus**: The **RouteShift** entry in the cross-product navigation bar on [locus.axiomancer.io](https://locus.axiomancer.io) now points to [routeshift.io](https://routeshift.io) instead of an unowned `.com` domain, so clicks from Locus no longer dead-end. * **Locus**: HTML-escaped the geocoded place name in the [free Location Report](https://locus.axiomancer.io/free-report) confirmation email body, closing a path where a maliciously crafted Mapbox `place_name` could inject markup into the rendered confirmation message. Subject lines continue to render the place name as readable text with control characters stripped. Legitimate report requests are unaffected. * **Codex**: The **RouteShift** entry in the cross-product navigation bar on [axiomcodex.io](https://axiomcodex.io) now points to [routeshift.io](https://routeshift.io) instead of an unowned `.com` domain, so clicks from Codex no longer dead-end. The brand mark in the bar was also refreshed to match the canonical RouteShift glyph. * **Axiomancer**: Tightened spacing on the [privacy](https://axiomancer.io/legal/privacy) and [terms](https://axiomancer.io/legal/terms) pages — long sections no longer leave awkward gaps between headings and paragraphs, and the pages read cleanly on both desktop and mobile. * **Axiomancer**: Session-replay privacy masking on [axiomancer.io](https://axiomancer.io) now stays applied under the current PostHog SDK. Visitor text and form input fields remain fully masked in any captured session replay, matching the behavior already documented in the [privacy policy](https://axiomancer.io/legal/privacy). No action is required on your part. * **Overwatch**: Hardened the cold [archive](/overwatch/data-retention#archive-storage) writer's credential handling — surrounding whitespace on archive credentials is trimmed before the upload signs, and credentials containing control characters now fail fast with a clear configuration error instead of producing an opaque "invalid character in header" runtime failure that could quietly stall historical-position archival. * **Overwatch**: [Commodity prices](/overwatch/api/market-data) are landing again. The benchmark-price ingestion path had been silently writing zero rows since March 30 against a retired upstream URL, leaving the [`/api/v1/commodity-prices`](/overwatch/api/market-data) feed stale on every series. The pipeline now reads IMF commodity series from the FRED API, with surfaced errors instead of swallowed failures, so wheat, corn, crude oil, iron ore, LNG, and the other tracked benchmarks resume daily refresh from the next run forward. Backfill of the gap window is in progress. * **Overwatch**: [Disruption signals](/overwatch/api/disruptions) ingestion is back on a sustainable cadence. The GDELT-backed news signal pipeline driving [`/api/v1/disruptions`](/overwatch/api/disruptions) had been hitting the upstream rate limit and silently dropping every run after deploying a stale build that swallowed errors. Query volume is now trimmed to stay under the GDELT daily cap and the worker has been redeployed to surface upstream failures, so port closures, sanctions, trade disputes, weather events, and canal blockages flow into the disruption feed and the supply-chain risk models that consume it on schedule. * **Overwatch**: [River-level](/overwatch/api/river-levels) readings are populating again. A column-name drift in the port-weather write path was rejecting every insert from the river-level fetcher, leaving Mississippi, Ohio, Illinois, Columbia, and Houston gauges stale on [`/api/v1/river-levels`](/overwatch/api/river-levels) and the matching `river_level` [alerts](/overwatch/api/alerts) silent. The schema mismatch is fixed and the worker has been redeployed onto the standard ingestion-log path, so live levels and `normal/low/critical/flood` status changes resume on cadence. * **Overwatch**: Brazil COMEX trade-flow ingestion is now scheduled. The monthly Brazil customs feed had no cron entry and was relying on manual triggers, leaving Brazil exports under-represented in the [trade flows](/overwatch/api/trade-flows) and [mirror-discrepancy](/overwatch/api/trade-flows) surfaces between operator runs. The job now runs on the 8th of each month at 06:00 UTC, in line with the upstream publish cadence, so Brazilian commodity exports flow into UN Comtrade reconciliation and downstream [forecasts](/overwatch/api/forecasts) without manual prompting. * **Overwatch**: Failed [vessel-visit](/overwatch/methodology/voyage-time-allocation) writes now stay retryable. When the visit pipeline failed to insert a new visit or update an in-progress visit to `loading`, the underlying port event was still being marked processed, so the failure dropped silently and never replayed. The pipeline now raises on the database error before clearing the event, leaving the source [port event](/overwatch/api/ports) in the queue for the next run, and the [`visit pipeline` status page](/overwatch/status-page) tile and `ingestion_logs` row now surface a readable Supabase error message instead of `[object Object]`. * **Overwatch**: Database-level idempotency for [AIS positions](/overwatch/api/vessels) and [port events](/overwatch/api/ports). Duplicate inserts — whether from an AIS worker retrying a transient batch or from concurrent processing pipelines racing on the same fix — are now silently skipped at the row level rather than landing as duplicate rows that downstream analytics had to dedupe later. The new guard keys off the upstream provider record ID when present and falls back to the natural identity (source + IMO + timestamp for positions; IMO + port + event type + timestamp for events) so heterogeneous feeds — AISHub, AIS Stream, satellite, Spire, and the port-event scrapers — all converge on a single canonical row. No user-facing behavior changes; vessel position freshness, [pairwise encounter extraction](/overwatch/methodology/encounter-extraction), [risk feeds](/overwatch/api/risk), and [vessel visit](/overwatch/methodology/voyage-time-allocation) accounting all continue exactly as before, with a cleaner upstream guarantee that duplicate rows can no longer creep into the live database. * **Layer**: [Plans and billing](/layer/billing) endpoints — checkout sessions and the Stripe customer portal — now require an admin or owner role on the workspace before they will start a session, with a clear `403` returned to non-admins instead of silently letting any authenticated member kick off a billing change. The same gate is enforced on the Drift dashboard. Existing admin and owner workflows are unchanged; member-tier accounts no longer see the **Manage billing** path act on the workspace. * **Drift**: Team [invites](https://axiomdrift.io) and member role changes now write the resulting workspace ID and role into the trusted Supabase `app_metadata` claim alongside the workspace membership row, so server-side authorization checks read from a single tamper-resistant source instead of reconstructing the role from a user-writable surface. Existing members keep their current role; new invites land as **viewer** and inherit any subsequent role change automatically. * **Layer / Drift**: PII in production error reports is now scrubbed before it leaves the dashboard. Email addresses, IP addresses, authorization headers, cookies, and form-field values matching common PII names are redacted in [Sentry](https://sentry.io) breadcrumbs, request payloads, and exception extras across the dashboard, Edge runtime, and server runtime, so engineering can keep diagnosing production errors without storing customer identifiers in the error stream. * **Drift**: The **Load sample data** action on a fresh [Drift](https://axiomdrift.io) workspace is wired up again — the seed endpoint had been writing against a stale `org_id` column and silently failing on every insert, leaving demo workspaces empty. Discovered apps, action items, and email receipts now seed cleanly into the new workspace on first click. The 5-row guard against re-seeding a workspace with existing data is unchanged. * **Layer**: The Apps, Assets, dashboard, and **Cost per employee** pages on the [Layer dashboard](https://app.axiomlayer.io) are populating again. A row-level security regression had silently zeroed every read for these views, so the pages rendered as empty even when the underlying inventory and spend data was intact. Reads now flow through the corrected tenant-resolution path, and the previously empty rollups, app lists, and asset tables surface their full contents on next load. * **Drift**: Dashboard reads on the [Drift](https://axiomdrift.io) Apps, Benchmarks, dashboard, Inventory, and Renewals pages now query the canonical workspace identifier instead of a stale legacy column, so paid workspaces no longer see an empty inventory or zeroed spend totals after the recent multi-tenant migration. * **Layer**: Sentry **Session Replay** is now disabled on every authenticated route in the [Layer dashboard](https://app.axiomlayer.io) and stops cleanly on client-side route transitions, so tenant data inside the dashboard never enters a replay buffer even on long-lived single-page navigations. Marketing-surface replay sampling is unchanged. * **Layer**: The public marketing surface and the sign-in / sign-up pages on the [Layer dashboard](https://app.axiomlayer.io) now render a friendly recovery screen with a **Try again** button when an unexpected server error occurs, instead of leaving the browser stuck on a blank page after a closed RSC stream. The dashboard, billing, and integrations surfaces — which already had their own error boundaries — are unaffected. * **Layer**: Adding a connector to a workspace now succeeds for every source in the [integrations catalog](/layer/integrations/overview). A registration step had been skipped for some new connectors, surfacing as an "unsupported source" error on first sync — most visibly for **Microsoft Entra ID**, which is now correctly aliased to its underlying directory connector. Existing connections are unaffected; new connections complete their first sync without manual retry. * **Axiomancer**: The scroll-driven platform reveal on [axiomancer.io](https://axiomancer.io) is visible again. A page-level overflow setting was preventing the sticky scroll behavior from engaging on descendant elements, leaving a tall blank section where the product reel should have been. Visitors now see the full scroll-driven reveal of the product lineup as intended. # May 9, 2026 (/changelog/2026-05-09) ## One-click OAuth now live for Slack, Notion, and Atlassian [#one-click-oauth-now-live-for-slack-notion-and-atlassian] Connecting [Slack](/layer/integrations/slack), [Notion](/layer/integrations/notion), and [Atlassian](/layer/integrations/atlassian) to Layer now uses the same one-click OAuth flow as [Google Workspace](/layer/integrations/google-workspace) and [Microsoft 365](/layer/integrations/microsoft-365). Click **Connect**, sign in with your admin account, and grant consent — no API tokens or service accounts required. ## OAuth integrations promoted to production [#oauth-integrations-promoted-to-production] All OAuth-brokered integrations — including [Google Workspace](/layer/integrations/google-workspace), [Microsoft 365](/layer/integrations/microsoft-365), [Intune](/layer/integrations/intune), Teams, and M365 Mail — are now running on the production identity provider. Token refresh, re-authorization flows, and the daily [integration health email](/layer/integrations/overview) all operate against the production tenant, improving reliability and reducing re-auth prompts. ## Updated landing page copy [#updated-landing-page-copy] The Layer landing page now accurately reflects the current product lineup and integration catalog. References to deprecated products have been removed, the integration count has been updated to match the live catalog, and the FAQ now explains the admin-consent OAuth experience. # May 11, 2026 (/changelog/2026-05-11) ## Hourly pairwise encounter extraction stops timing out [#hourly-pairwise-encounter-extraction-stops-timing-out] Roughly half of hourly [pairwise encounter](/overwatch/methodology/encounter-extraction) runs had been failing with a statement timeout on the densest 90-minute windows — the scan paginating through tens of thousands of [AIS positions](/overwatch/api/vessels) per window was scaling linearly with table size and tipping over past page 4. The extractor now pages forward through the primary-key index instead, so each step is a constant-time seek and the full hour completes well under the statement timeout. Encounter geometry — CPA, TCPA, range, closing speed, and COLREGS posteriors — resumes landing on schedule in the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) feeds, and backfill of the gap window is in progress. ## H3 spatial-index backfill on AIS positions resumes [#h3-spatial-index-backfill-on-ais-positions-resumes] The H3 spatial-index backfill on [AIS positions](/overwatch/api/vessels) had been silently retrying without progress for roughly 13 days as the batch size outgrew what the database could finish inside a single statement window, leaving a tail of older positions without their H3 cell assigned. The batch size has been tuned down so each pass clears the window cleanly, the cursor is advancing again, and spatial joins against [density](/overwatch/api/density), [ports](/overwatch/api/ports), and [chokepoint](/overwatch/methodology/chokepoint-transits) layers will reflect the full historical record once the backfill catches up. ## Heavy recurring jobs move onto a dedicated worker [#heavy-recurring-jobs-move-onto-a-dedicated-worker] Several heavy recurring jobs — per-port water-density refresh feeding [hydrostatic cargo validation](/overwatch/methodology/cargo-validation), temporal-motif scoring on [pairwise encounters](/overwatch/methodology/encounter-extraction), weekly [trade-flow](/overwatch/api/trade-flows) aggregation, and the [benchmark spoofing detector](/overwatch/api/risk) — now run on a dedicated persistent worker instead of sharing the database cron pool. The jobs continue to land on their existing cadences with a 5-minute heartbeat and graceful restart, so transient database pressure no longer skips a scheduled run. No configuration changes are required on your part. # Week of May 10–16, 2026 (/changelog/2026-05-16-weekly) ## This week at a glance [#this-week-at-a-glance] A quiet week after a heavy [May 3–9 release](/changelog/2026-05-09-weekly). Codex shipped a structured evidence map across four major compliance frameworks — [SOC 2](/codex/soc2-evidence-catalog), [ISO 27001](/codex/iso27001-evidence-catalog), [HIPAA](/codex/hipaa-evidence-catalog), and [PCI DSS](/codex/pci-dss-evidence-catalog) — so each control links directly to the integrations that supply its evidence, the collection cadence, and the level of automation. Overwatch hardened [pairwise encounter extraction](/overwatch/methodology/encounter-extraction) so the hourly run stops timing out on busy windows, restarted the H3 spatial-index backfill on [AIS positions](/overwatch/api/vessels), and moved several heavy recurring jobs — port water-density refresh, temporal-motif scoring, weekly trade-flow aggregation, and the [benchmark spoofing detector](/overwatch/api/risk) — onto a dedicated persistent worker. Layer's pricing FAQ was clarified to match the live plan lineup, and Locus picked up its scheduled ML weights refresh. ### New features [#new-features] * **Codex**: Structured evidence mapping across four frameworks. The new [SOC 2](/codex/soc2-evidence-catalog) (11 controls), [ISO 27001](/codex/iso27001-evidence-catalog) (10 controls), [HIPAA](/codex/hipaa-evidence-catalog) (8 controls), and [PCI DSS](/codex/pci-dss-evidence-catalog) (7 controls) catalogs each break a control down into the specific integrations that provide evidence for it, the collection cadence, and whether evidence collection is fully automatic, partially automatic, or manual. Useful for showing an auditor exactly what Codex is collecting on your behalf, where it's coming from, and how often it refreshes — all in one view per framework. ### Updates [#updates] * **Layer**: The [pricing FAQ](https://axiomlayer.io) now reflects the current plan lineup. The free tier — up to 25 employees with [Google Workspace](/layer/integrations/google-workspace) — remains fully self-serve. Paid tiers are launching soon; reach out to [sales@axiomancer.io](mailto:sales@axiomancer.io) for early access. * **Overwatch**: Several heavy recurring jobs — per-port water-density refresh feeding [hydrostatic cargo validation](/overwatch/methodology/cargo-validation), temporal-motif scoring on [pairwise encounters](/overwatch/methodology/encounter-extraction), weekly [trade-flow](/overwatch/api/trade-flows) aggregation, and the [benchmark spoofing detector](/overwatch/api/risk) — now run on a dedicated persistent worker instead of sharing the database cron pool. The jobs continue to land on their existing cadences with a 5-minute heartbeat and graceful restart, so transient database pressure no longer skips a scheduled run. No configuration changes are required on your part. * **Locus**: Scheduled ML model weights refresh landed on the regular cadence, keeping the [cell scoring](/locus/scoring-conventions) and [pioneer-signal](/locus/scoring-conventions) inference paths trained against the most recent calibration window. No action required; the refresh ships transparently into the live scoring surface. ### Fixes [#fixes] * **Overwatch**: Hourly [pairwise encounter extraction](/overwatch/methodology/encounter-extraction) is durable against busy windows. Roughly half of hourly runs had been failing with a statement timeout on the densest 90-minute windows — the scan paginating through tens of thousands of [AIS positions](/overwatch/api/vessels) per window was scaling linearly with table size and tipping over past page 4. The extractor now pages forward through the primary-key index instead, so each step is a constant-time seek and the full hour completes well under the statement timeout. Encounter geometry — CPA, TCPA, range, closing speed, and COLREGS posteriors — resumes landing on schedule in the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) feeds, and backfill of the gap window is in progress. * **Overwatch**: The H3 spatial-index backfill on [AIS positions](/overwatch/api/vessels) is moving forward again. The job had been silently retrying without progress for roughly 13 days as the batch size outgrew what the database could finish inside a single statement window, leaving a tail of older positions without their H3 cell assigned. The batch size has been tuned down so each pass clears the window cleanly, the cursor is advancing again, and spatial joins against [density](/overwatch/api/density), [ports](/overwatch/api/ports), and [chokepoint](/overwatch/methodology/chokepoint-transits) layers will reflect the full historical record once the backfill catches up. # May 16, 2026 (/changelog/2026-05-16) ## Structured evidence mapping across four compliance frameworks [#structured-evidence-mapping-across-four-compliance-frameworks] Codex now includes a structured evidence map covering 36 controls across [SOC 2](/codex/soc2-evidence-catalog) (11 controls), [ISO 27001](/codex/iso27001-evidence-catalog) (10 controls), [HIPAA](/codex/hipaa-evidence-catalog) (8 controls), and [PCI DSS](/codex/pci-dss-evidence-catalog) (7 controls). Each control is linked to the specific integrations that provide evidence for it, along with collection cadence and whether evidence collection is fully automatic, partially automatic, or manual. This gives you a clear, per-control view of what Codex collects, where it comes from, and how often it refreshes. ## Pricing FAQ clarified [#pricing-faq-clarified] The Layer pricing FAQ now accurately reflects available plans. The free tier (up to 25 employees with Google Workspace) remains fully self-serve. Paid tiers are launching soon — for early access, reach out to [sales@axiomancer.io](mailto:sales@axiomancer.io). # May 18, 2026 (/changelog/2026-05-18) ## Live-map positions endpoint no longer times out [#live-map-positions-endpoint-no-longer-times-out] The public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint that powers the live map and the marketing hero map now returns reliably under load. A dead-weight exact-count query against the latest-positions view was hitting the database's 10-second statement timeout under heavy traffic and surfacing as 500s in Sentry. The response shape is unchanged. `total_vessel_count` continues to match the returned feature count on both bounded and unbounded paths, and existing live-map consumers fall back to the viewport count when total isn't present. No client changes are required. ## Dark events archive cron no longer times out [#dark-events-archive-cron-no-longer-times-out] The nightly archive job that rolls older [dark events](/overwatch/api/risk) into cold storage had been getting cancelled by the database's 10-second statement timeout. The range scan that walks events older than the retention cutoff now uses a dedicated index, so the cron completes as a cheap index walk instead of a sequential scan plus sort. Archival is current again, and dark-event queries against recent windows continue to perform unchanged. ## FOIA portal automation and Granicus council-meeting tagging [#foia-portal-automation-and-granicus-council-meeting-tagging] Locus's automated FOIA submission flow for [foia.gov](/locus/business-licenses) now follows the portal's current React-based workflow — agency search, agency detail, and per-component request form — instead of the retired `/request/` URL. The submitter dispatches proper synthetic events on the React-controlled fields. Captcha-protected agencies are now reported with a clear `captcha_detected` marker in monitoring instead of opaque selector timeouts, so the real blocker is visible at a glance. Separately, Granicus-hosted council meetings now consistently carry the correct metro tag at ingest, matching the parity already in place for Legistar cities and keeping cross-metro filters on the council-meeting feed accurate. # May 19, 2026 (/changelog/2026-05-19) ## GLEIF corporate relationships now feed UBO traversal and the entity graph [#gleif-corporate-relationships-now-feed-ubo-traversal-and-the-entity-graph] Overwatch and Codex now ingest the [GLEIF Level 2](https://www.gleif.org/en/lei-data/gleif-relationship-record/) corporate relationship dataset — direct and ultimate parent/child links between any two LEI-registered entities worldwide — and refresh it weekly. The new data lands as `Ownership` edges on the [Codex entity graph](/codex/entity-graph) alongside the existing vessel, sanctions, and civic networks, and flows into Overwatch's [vessel ownership traversal](/overwatch/api/ubo) so corporate parents above the directly registered owner are now walked automatically when matching against sanctions lists. Multi-hop exposures through holding structures that were previously invisible — a sanctioned ultimate parent two or three corporate layers above a vessel's registered owner — now surface on the vessel's risk profile and in the [unified alerts inbox](/overwatch/api/alerts). License: CC0. ## Ultimate-parent lookup for any LEI [#ultimate-parent-lookup-for-any-lei] A new ultimate-parent chain lookup returns the full consolidated-ownership path from any LEI up to its ultimate parent in a single call, with a hard depth cap of 10 hops and only active `IS_ULTIMATELY_CONSOLIDATED_BY` relationships traversed. Useful for resolving "who ultimately owns this counterparty" without stitching together hop-by-hop GLEIF lookups by hand. Exposed on the [beneficial ownership API](/overwatch/api/ubo) for entities linked to a tracked vessel, and available across the broader LEI universe via the [entity graph export](/codex/entity-graph) on Enterprise. Call it from the Supabase JS / Python client as a standard RPC, or directly in SQL — execute is granted to `anon`, `authenticated`, and `service_role`. The data is CC0 Public Domain and slots in alongside the vessel-scoped [`/api/v1/ubo/vessel/{imo}`](/overwatch/api/ubo) graph for [sanctions screening](/overwatch/api/sanctions) and manual UBO investigations. See [GLEIF ultimate parent chain](/overwatch/api/ubo#gleif-ultimate-parent-chain) for the full schema, examples, and call signature. # Week of May 17–23, 2026 (/changelog/2026-05-23-weekly) ## This week at a glance [#this-week-at-a-glance] A short, focused week after the heavier [May 10–16 recap](/changelog/2026-05-16-weekly). Locus picked up a new **Recent hazards** panel on every [cell detail](/locus/api/enrichment) page, surfacing NASA FIRMS active fires and USGS earthquake history inside the exact H3 footprint you're looking at. Overwatch shipped two reliability fixes — the public live-map [positions endpoint](/overwatch/api/vessels) no longer times out under load, and the nightly [dark events](/overwatch/api/risk) archive cron is completing cleanly again. Locus's automated [FOIA portal submitter](/locus/business-licenses) was retargeted at the current foia.gov React workflow, and Granicus-hosted council meetings are now tagged to the correct metro at ingest. A focused week. Locus replaced the placeholder visualizations on the cell [score breakdown](/locus/scoring-conventions) and on the [Explorer](/locus/explorer) score-history sidebar with real visx-powered charts wired to live data — a new **score components** bar sits beside the radar octagon on the location detail surface, and the explore sidebar's score-history view now plots composite and per-group trends from `/api/score-trends` instead of the prior static placeholder. Overwatch restored Marshall Islands IRI [vessel-registry enrichment](/overwatch/api/vessels) after the upstream search portal swapped to a new form layout — the adapter now handles both the new and legacy DOM, with a deterministic parser writing typed vessel records into the enrichment queue. The Splink-based probabilistic record-linkage scaffolding also landed under the hood; cross-registry deduplication for [sanctions](/overwatch/api/sanctions) and [UBO](/overwatch/api/ubo) consumers ships in a follow-up once training data and downstream wiring are in place. Daily releases this week — the [live-map positions endpoint](/changelog/2026-05-18), the [dark-events archive cron](/changelog/2026-05-18), and Locus's [FOIA portal automation](/changelog/2026-05-18) — are recapped at the linked dailies ### New features [#new-features] * **Locus**: New **Recent hazards** section on every [cell detail](/locus/api/enrichment) page. Shows NASA FIRMS active-fire detections from the trailing 180 days (with fire radiative power per detection) and USGS earthquakes from the trailing 5 years (with max magnitude and per-event magnitude and type), joined on H3 equality so the panel answers "what happened *here*" rather than "what happened nearby." Cells in low-hazard geographies render a clean empty state. Pairs with the existing [safety and environment](/locus/scoring-conventions) signal group, but exposes the underlying detections directly instead of only a rolled-up score. * **Locus**: Real **score components** bar chart now sits beside the radar octagon on the cell [score breakdown](/locus/scoring-conventions). Each of the eight canonical signal groups — `business_vitality`, `population_momentum`, `demographics`, `economic_strength`, `development_pipeline`, `accessibility`, `safety_environment`, `amenity_demand` — renders as a sortable bar with its 0–100 sub-score, weight, and confidence chip, replacing the prior placeholder. The radar octagon is unchanged, so existing reads of dominant-signal geometry still work side-by-side with the new at-a-glance bar comparison. * **Locus**: The score-history chart in the [Explorer](/locus/explorer) left sidebar is now a real interactive time series. The chart pulls from `/api/score-trends` for the currently selected cell, ships the composite line plus per-group lines for business, population, economic, safety, and accessibility, and lets you toggle between 30-, 60-, and 90-day windows. Hover any point for the composite and per-group values on that date. ### Fixes [#fixes] * **Overwatch**: The public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint powering the live map and the marketing hero map is no longer timing out under load. A dead-weight exact-count query against the latest-positions view had been hitting the database's 10-second statement timeout during traffic spikes and surfacing as 500s. The response shape is unchanged — `total_vessel_count` still matches the returned feature count on both bounded and unbounded requests, and live-map consumers continue to fall back to the viewport count when total isn't present. No client changes required. * **Overwatch**: The nightly [dark events](/overwatch/api/risk) archive cron — which rolls older events into cold storage — is current again. The range scan that walks events older than the retention cutoff now uses a dedicated index, so the job completes as a cheap index walk instead of a sequential scan plus sort and no longer trips the database statement timeout. Dark-event queries against recent windows continue to perform unchanged. * **Locus**: Automated [FOIA portal submission](/locus/business-licenses) for foia.gov follows the portal's current React-based workflow — agency search, agency detail, and per-component request form — instead of the retired `/request/` URL, with proper synthetic events dispatched on the React-controlled fields. Captcha-protected agencies are now reported with a clear `captcha_detected` marker in monitoring instead of opaque selector timeouts, so the real blocker is visible at a glance. * **Locus**: Granicus-hosted [council meetings](/codex/schemas/civic-intelligence) now consistently carry the correct metro tag at ingest, matching the parity already in place for Legistar cities. Cross-metro filters on the council-meeting feed stay accurate. * **Overwatch**: Marshall Islands IRI [vessel-registry enrichment](/overwatch/api/vessels) is producing typed records again. The IRI search portal migrated to a new ADF-based form (live `pt1:r1:0:it2` IMO field and a text-anchored **Search** button); the scraper had been timing out on the retired `imoNumber` field and the old submit selector and stalling enrichment jobs against Marshall Islands vessels. The adapter now races the new and legacy selectors, falls back automatically when the page reverts, and feeds a deterministic parser that writes `imo_number`, `official_number`, `vessel_name`, and `found` directly into the enrichment record instead of relying on downstream HTML parsing. Raw HTML is retained on each result during rollout so any label-alias drift can be retro-parsed without re-scraping. IRI enrichment lag clears forward from the next worker run. # May 23, 2026 (/changelog/2026-05-23) ## Compliance and backfill monitoring dashboard [#compliance-and-backfill-monitoring-dashboard] Codex now includes a compliance monitoring dashboard that shows APRS envelope coverage percentages across all tracked tables at a glance. You can see per-table adoption rates for key metadata fields — including `record_id`, `source_uri`, `h3_index`, and `mmsi` — without running manual queries. A companion backfill progress view tracks job run counts, rows updated, and time since last run, automatically flagging stalled jobs so you can catch issues early. Both views refresh from live database statistics. ## Vessel enrichment session recovery fix [#vessel-enrichment-session-recovery-fix] Fixed a bug where the vessel enrichment pipeline's retry logic for expired data-source sessions wasn't using the re-fetched data. When a session expired mid-batch, the pipeline re-authenticated and fetched fresh data but then discarded it, causing the entire batch of vessels to fail silently and back off for six hours. Enrichment data now recovers immediately on session expiry instead of waiting for the next scheduled run. # May 30, 2026 (/changelog/2026-05-30) ## APRS envelope metadata backfill fix [#aprs-envelope-metadata-backfill-fix] Fixed an issue where some Codex records had incomplete APRS envelope metadata — specifically, rows with a `record_id` were missing the corresponding `chunk_id`. This caused the [envelope coverage dashboard](/codex/envelope-coverage) to underreport compliance percentages for affected tables. All existing records now carry the full set of APRS metadata fields, and coverage numbers reflect the true state of your data. # June 6, 2026 (/changelog/2026-06-06) ## APRS envelope on Brazil commodity data sources [#aprs-envelope-on-brazil-commodity-data-sources] Five additional data sources now carry full APRS metadata from the moment records are written — USACE lock passages, ANTAQ vessel calls, CONAB crop reports, ANTT road freight rates, and CEPEA commodity prices. Each record receives a stable URN, schema version, source attribution, and timestamp fields at insert time, so new data is immediately audit-ready without waiting for a backfill cycle. This is part of the ongoing rollout to bring every Codex data source into full [APRS compliance](/codex/envelope-coverage). ## Event history APRS backfill complete [#event-history-aprs-backfill-complete] Historical event records that predated the APRS envelope rollout have been backfilled with full metadata — including `record_id`, `chunk_id`, `source_uri`, and timestamps. Coverage on the events table jumped from around 2% to near-complete. The [envelope coverage dashboard](/codex/envelope-coverage) now reflects accurate compliance percentages for this table. No action is required on your part; the backfill ran automatically. # June 13, 2026 (/changelog/2026-06-13) ## In-app live chat support [#in-app-live-chat-support] Layer now includes an Intercom chat widget so you can reach support directly from your dashboard without leaving the app. When you're signed in, the widget automatically identifies you — so the support team sees your name and email without you having to repeat it. If you're not signed in (for example, during a login issue), the widget still loads in anonymous mode so you can get help. # June 20, 2026 (/changelog/2026-06-20) ## Automated data source discovery [#automated-data-source-discovery] Locus now continuously scans for new public data sources and uses AI to evaluate whether each one is worth adding to the platform. Promising datasets are surfaced in a weekly email digest that includes a data preview, column count, and row count — so you can see what's available without leaving your inbox. This means Locus data coverage grows automatically as new government and public datasets come online, without any action on your part. ## Port event records now APRS-compliant [#port-event-records-now-aprs-compliant] Port event data now carries full APRS metadata — including `record_id`, `source_uri`, and vessel identifiers — bringing this table in line with the rest of the Codex catalog. Port event records are now audit-ready from the moment they're written. See the [envelope coverage dashboard](/codex/envelope-coverage) for current compliance percentages. ## Platform performance improvements [#platform-performance-improvements] Query performance across the platform has been improved through a database optimization pass — duplicate indexes were removed, missing primary keys were added, and frequently queried foreign keys were indexed. You may notice faster load times on pages that display vessel data, maritime links, and corridor information. # June 27, 2026 (/changelog/2026-06-27) ## Cleaner integration catalog [#cleaner-integration-catalog] The [integrations](/layer/integrations/overview) page now only shows connectors with fully working backends. 43 catalog entries that accepted credentials but couldn't actually sync data have been removed, so every connector you see is ready to use. If you need a connector that isn't listed yet, use the new **Request a connector** button to let us know — requests go directly to the product team and help prioritize what ships next. # Week of June 28–July 4, 2026 (/changelog/2026-07-04-weekly) ## This week at a glance [#this-week-at-a-glance] Quiet week focused on one big lift: Overwatch's AIS worker is now ready for [worldwide vessel coverage](/overwatch/ais-coverage). Flipping `AISSTREAM_GLOBAL=1` used to mean subscribing to \~175K vessels with the same write path used for a few thousand — enough to overwhelm the database. The worker now separates in-zone traffic (unchanged, full history and analytics) from out-of-zone traffic, which flows through a per-vessel throttled buffer into the latest-known-position table that powers the live map. In-zone behavior is byte-for-byte identical, so nothing changes until you opt in. ### Updates [#updates] * **Overwatch**: [Worldwide AIS coverage](/overwatch/ais-coverage) is now safe to enable. When `AISSTREAM_GLOBAL=1` is on, positions inside your monitored port and chokepoint boxes keep their full pipeline — position history, dark-event detection, course-anomaly flags, and other analytics all run exactly as before. Positions outside those zones become map-only data: they refresh the last-known vessel state that feeds the live map's worldwide layer, but they no longer write per-position history rows or trigger analytics side-effects. Vessels are still marked "seen" everywhere they broadcast, so a vessel that transits ocean and then re-enters a monitored zone doesn't produce a false dark-event gap. * **Overwatch**: New tuning knobs on the AIS worker for global mode — `GLOBAL_BACKGROUND_MIN_INTERVAL_S` (minimum seconds between writes per out-of-zone vessel, default 600), `GLOBAL_BACKGROUND_FLUSH_MS` (buffer flush cadence, default 30s), `GLOBAL_BACKGROUND_UPSERT_CHUNK` (rows per write, default 500), `STATIC_DATA_DB_MIN_INTERVAL_S` (Type 5 static-data write throttle, default 6h), `MMSI_RECOVERY_RETRY_S` (unknown-MMSI recovery throttle, default 30 min), and `AIS_MAX_STUBBED_IMOS` (stub-vessel cache size, default 300,000). Defaults are tuned for the \~175K-vessel global fleet; leave them alone unless you have a reason to change them. See [AIS coverage](/overwatch/ais-coverage) for the setup. ### Fixes [#fixes] * **Overwatch**: The AIS worker's feed-stall watchdog now counts out-of-zone background writes when global coverage is on. Previously it only counted in-zone position ingestion, so a stretch of purely out-of-zone traffic (common in global mode) could be misread as a stalled feed and force-restart a healthy worker. * **Overwatch**: A transient database error during unknown-vessel lookup or static-data ingestion no longer silences retries for the full throttle window. Failed attempts release the throttle immediately, so the next incoming message for the same vessel triggers a fresh try instead of waiting 30 minutes (unknown-MMSI recovery) or 6 hours (static data). # July 4, 2026 (/changelog/2026-07-04) ## Six new first-class integrations [#six-new-first-class-integrations] Datadog, CrowdStrike, GitHub, Azure, GCP, and AWS connectors are now fully operational in Layer's discovery system. Previously, these connectors relied on a legacy sync path that could miss data or fail silently. All six now handle end-to-end sync — connect once and Layer continuously discovers and inventories your assets: * **Datadog** — monitors, downtimes, and log indexes * **CrowdStrike** — device inventory, detections, and prevention policies * **[GitHub](/layer/integrations/github)** — repo and org inventory, plus Copilot seat utilization * **Azure** — subscriptions, resource groups, and RBAC role assignments * **GCP** — IAM bindings and audit logs * **[AWS](/layer/integrations/aws)** — IAM, STS, and S3 bucket inventory If you previously connected any of these providers, your next sync will automatically use the new pipeline — no action required. See the [integrations overview](/layer/integrations/overview) for setup details. ## Worldwide AIS coverage, without the write storm [#worldwide-ais-coverage-without-the-write-storm] Overwatch is ready for planet-wide [AIS coverage](/overwatch/ais-coverage). When global mode is enabled, in-zone behavior is unchanged — [vessels](/overwatch/api/vessels) inside your monitored port zones still get full position history, dark-event detection, and course-anomaly analytics. Vessels outside those zones now flow through a latest-wins, per-vessel throttle into the live map's worldwide last-known layer, so the map shows every AIS-broadcasting vessel (\~175K) without amplifying database writes. New per-vessel throttles for global-mode operators cover out-of-zone position writes, static-data upserts, and unknown-vessel recovery — all env-tunable with production-safe defaults. If you stay in port-based coverage (the default), nothing changes. # July 9, 2026 (/changelog/2026-07-09) ## Six new Codex research-tier datasets on Hugging Face [#six-new-codex-research-tier-datasets-on-hugging-face] Codex now publishes six additional [research-tier](/codex/data-catalog) datasets on the [Axiom AI Hugging Face organization](https://huggingface.co/axiom-ai), each a deterministic 100K-record stratified sample in Parquet under CC-BY-4.0: * [AIS Maritime](/codex/schemas/ais-maritime) * [Civic Intelligence — Events Timeline](/codex/schemas/events-timeline) * [OSHA Safety](/codex/schemas/osha-safety) * [LEHD Commuter Flows](/codex/schemas/lehd-commuter-flows) (workplace jobs) * [POI Intelligence](/codex/schemas/poi-intelligence) * [Permit Signals](/codex/schemas/permit-signals) Every dataset ships with a README, schema documentation, and the standard [APRS envelope](/codex/normalization-standard) — so the loading patterns in the [Codex notebooks](/codex/notebooks) work against any of them without changes. ### Fixes [#fixes] * **Locus**: The **building-inspection records** dataset now carries the correct `source_uri` on every row across all four covered metros — Chicago, Los Angeles, New York City, and San Francisco. `source_uri` is now derived per-row from each row's `source_name` (its Socrata `domain/dataset_id`) rather than assumed to be a single hardcoded URL, so citations, re-fetches, and downstream joins from [Codex](/codex/normalization-standard) resolve to the correct metro's Socrata endpoint. Today's 4,299 rows (all Chicago at the time of the fix) are unchanged; the correction is forward-looking — LA, NYC, and SF rows landing from the weekly `--all` scout run will be tagged with their own metro's source URL from ingest onward. * **Locus**: **USDA SNAP retailers** — the nationwide food-retailer roster that feeds the *food access* sub-signal in the [`amenityDemand`](/locus/scoring-conventions) group — is now deduplicated and kept fresh incrementally. A silent failure in the previous monthly reload had let each snapshot stack on top of the last instead of replacing it, leaving 544,419 excess rows across 256,669 duplicate retailer IDs. The table has been cleaned to one row per retailer, a uniqueness constraint on the retailer ID prevents recurrence, and the refresh job now upserts by retailer ID with resumable checkpoints instead of truncate-and-reload — so partial-run failures no longer leave the table empty or duplicated. No action is required on your part; food-access scoring is now driven by an accurate retailer count and the roster stays current between monthly USDA publications. * **Overwatch**: The analytical charts on [Forecasts](/overwatch/api/forecasts), [Estimates](/overwatch/api/estimates), [Fleet](/overwatch/api/fleet) (age histogram and age-trend), [Berth](/overwatch/api/berth) utilization, seasonality panels, ownership-graph visualizations, and the Locus score-history panel on the [locus-validation](/locus/scoring-conventions) view now render cleanly during layout transitions. Three earlier passes had guarded the terminal-panel charts against a Recharts zero-dimension render warning, but ten charts elsewhere in the app were still unguarded and could briefly render at negative width or height (or flash a console warning) whenever their container measured before layout settled. All chart surfaces are now guarded uniformly, and a repository-wide check keeps new charts from regressing. # July 10, 2026 (/changelog/2026-07-10) ## Preset version history in the RouteShift dashboard [#preset-version-history-in-the-routeshift-dashboard] Named [presets](/routeshift/routing) — the saved bundles of model, parameters, system prompt, and provider preferences you attach to routing rules — now expose their full version history in the dashboard. Every time a preset is edited, RouteShift already writes a snapshot to `preset_versions`; two new authenticated, team-scoped endpoints let the dashboard list those snapshots and open any single one: * List every past version of a preset (newest first), including the model, params, system prompt, provider preferences, author, and timestamp for each revision. * Open a specific historical version by number to compare or copy fields back into the current preset. Access is strictly team-scoped: a preset that belongs to another workspace returns the same `preset_not_found` response as one that doesn't exist, so version numbers can't be used to probe other teams. Malformed slugs and out-of-range versions are rejected before any database read. ## Live web search as a per-request plugin [#live-web-search-as-a-per-request-plugin] RouteShift now runs live web search inside the proxy as a per-request [plugin](/routeshift/plugins), so any model can be given fresh context without your client wiring a separate search API. Two ways to opt in on any request: * Add a `:online` suffix to the model name (`gpt-4o:online`, `claude-3-5-sonnet:online`) for zero-config search with defaults. * Pass a `plugins` array with `{"id": "web", "max_results": …, "search_prompt": "…"}` for per-request control over how many results to fetch and the exact query to run. Results are injected into the system prompt as a clearly-delimited untrusted-context block, and the `plugins` array is stripped before the request reaches the upstream provider — providers never see RouteShift-specific fields. Two safety semantics carry through: * **Optional** (default) plugin failures return a `warnings` entry on the response and the underlying model call proceeds normally. * **Required** plugin failures (`"required": true`) fail closed with `502 plugin_required_failed`, so a caller that depends on fresh context never silently gets a stale answer. Plugin-enabled requests are non-cacheable in either direction, so search results always reflect a live call and never resurface on a cache hit. Web-search invocations carry a fixed per-call surcharge that appears on your [usage feed](/routeshift/observability); see [Savings and pricing](/routeshift/savings-and-pricing). ## Versioned request presets with immutable history [#versioned-request-presets-with-immutable-history] [Presets](/routeshift/presets) — team-scoped bundles of a canonical model, sampling parameters, system prompt, and provider preferences — now expose two new authenticated, team-scoped version-history routes: * `GET /api/presets/{slug}/versions` — every snapshot for a slug, newest first. * `GET /api/presets/{slug}/versions/{version}` — one immutable snapshot by integer version. Every accepted `POST` and `PUT` on a preset already appended a `preset_versions` row; those rows are now readable so you can diff a bad change, audit who touched what and when, and roll back by replaying an earlier snapshot as a `PUT` (there's no `POST /rollback` — history stays linear and append-only). Cross-team requests return the same `preset_not_found` response as a truly missing slug, so a team can't probe another team's namespace. Slugs are validated against `^[a-z0-9][a-z0-9-]{0,63}$` and versions against the PostgreSQL `int4` range before any database lookup. Demo mode reads the demo workspace's history transparently; demo writes stay blocked. ## Four FOIA-derived datasets now shape Locus cell scores [#four-foia-derived-datasets-now-shape-locus-cell-scores] Four new civic datasets received through the [FOIA request program](/locus/dashboard) are now live inputs to [Locus scoring](/locus/scoring-conventions), covering federal real-estate presence, broker-discipline actions, utility-service complaints, and nuclear-reactor proximity: * **GSA FRPP federal leases** (7,212 rows) → [`economicStrength`](/locus/scoring-conventions). Rentable-square-footage of federally-leased space is now summed inside the H3 res-8 query ring around each cell, so scoring reflects the concentration of federal tenants nearby. * **DOS broker discipline** (62 rows) → [`businessVitality`](/locus/scoring-conventions). Applied as a state-level penalty (the source carries no address or coordinates), so a cell in a state with an elevated recent-discipline count sees a small vitality drag. * **ICC utility complaints** (8,665 rows, mostly Illinois) → [`safetyEnvironment`](/locus/scoring-conventions). Joined at the ZIP-code level via the same nearest-ZIP RPC used by the FEMA flood signal. * **NRC reactor units** (116 units — 94 operating, 22 decommissioning) → [`safetyEnvironment`](/locus/scoring-conventions). Distance from each cell to the nearest reactor site is compared against the NRC's 16 km and 80 km Emergency Planning Zone radii. The dataset arrived without geolocation; a plant-name → site-coordinate crosswalk (68 sites) was built to back the signal. Nothing changes in how you call scoring — the four groups above pick up the new inputs on the next scheduled recompute. ### Updates [#updates] * **Codex**: GSA FRPP leases are now projected into [`codex_entities`](/codex/entity-graph) as `entity_type=facility`, and DOS broker-discipline actions into [`codex_events`](/codex/entity-graph) as `event_type=broker_disciplinary_action`. Both projections run on a continuous drain, so new source rows appear in the [entity graph](/codex/entity-graph) within a minute of landing. * **Locus**: The [HMDA](https://www.consumerfinance.gov/data-research/hmda/) loader that powers the [Highest Mortgage Activity ranking](/locus/mcp-server) and the multifamily / construction-loan signals in [`amenityDemand`](/locus/scoring-conventions) now filters multifamily loans client-side using the CFPB's `derived_dwelling_category`, instead of relying on a `property_types=3` server parameter that silently stopped being honored upstream. `hmda_agg.multifamily_loans` and `hmda_agg.construction_loans` will start reflecting real volumes on the next refresh instead of the zeros the legacy path silently produced. A hard per-state ceiling and a `derived_dwelling_category`-present check now fail the ingest loudly if the upstream shape shifts again. * **Locus**: Longer per-run timeouts for the HMDA, Legistar council-minutes, and MAUP tract → H3 areal-weight loaders on the [continuous-collection scheduler](/locus/dashboard). All three were routinely exceeding the previous global 3600-second ceiling and being reaped mid-run; runs can now complete cleanly on the observed 3,600–4,240 s durations. Paired with a separate streaming-memory fix, HMDA and Legistar should return to green. ### Fixes [#fixes] * **Locus**: The `qcew_construction` loader — construction-sector Quarterly Census of Employment & Wages, an input to the [`businessVitality`](/locus/scoring-conventions) and [`economicStrength`](/locus/scoring-conventions) groups — now actually loads rows. Three bugs (an incorrect owner-code filter, a renamed source column, and an off-by-one on the release-quarter lag) had combined to keep the table empty since the source was added; all three are corrected and the next scheduled run will backfill from the earliest available quarter. * **Locus**: The collector's OpenSanctions ingest (\~126K rows per run) no longer trips false "dead upstream" alerts. The scheduler's health check reads a fetched/upserted count out of each loader's completion log line; the OpenSanctions log line had drifted out of the expected shape, so successful runs were being paged as failures. The line is back to the canonical format and health alerts once again reflect reality. ## Web search plugin for any chat completion [#web-search-plugin-for-any-chat-completion] Any chat completion routed through RouteShift can now be augmented with fresh, cited web results — no client changes, no separate search integration. See [Web search](/routeshift/web-search). Two ways to opt in per request: * **Model suffix.** Append `:online` to the model name (for example, `gpt-4o:online`). The suffix is stripped before dispatch and a default `web` plugin is attached. * **Explicit plugin entry.** Add a `web` object to the top-level `plugins` array to tune `max_results`, pass a custom `search_prompt`, or mark the plugin as `required`. RouteShift runs the search, formats the top results as a clearly labeled context block, appends them to the system prompt, and forwards the request to the upstream provider — the model sees titles, URLs, and snippets, and never sees a raw `plugins` field. Augmented turns are non-cacheable, so time-sensitive results are never replayed and the per-search surcharge is charged exactly once. Failure modes are explicit: a missing or transient backend surfaces a warning header (`X-RouteShift-Plugin-Warning`) alongside a normal completion, unless the caller sets `required: true` — in which case the request fails cleanly with `plugin_required_failed` instead of returning a silently un-augmented response. ## Preset writes now report proxy-cache invalidation status [#preset-writes-now-report-proxy-cache-invalidation-status] Every write against a [preset](/routeshift/presets) — create, update, disable, delete — invalidates the proxy's in-memory preset cache so the next request sees the new configuration immediately. Previously, if that cache invalidation call failed after the database write had already committed, the API returned a plain success and the caller had no way to know the proxy would keep serving the stale preset until its TTL expired. Preset write responses now include an explicit outcome for the cache-invalidation step: * On success: `"proxy_cache_invalidated": true`. * On failure: `"proxy_cache_invalidated": false`, `"proxy_cache_error": "proxy_cache_invalidation_failed"`, and `"cache_ttl_seconds"` so you know how long the stale entry may linger. The database write is still committed either way — partial success is reported honestly rather than masked. Dashboards and CI pipelines that update presets can now surface a clear signal when a config change is written but not yet visible on the routing path. # Week of July 5–11, 2026 (/changelog/2026-07-11-weekly) ## This week at a glance [#this-week-at-a-glance] A focused RouteShift release week. Employees at a Google Workspace or Okta org can now sign in to the RouteShift CLI with real SSO and get a short-lived, self-service [virtual key](/routeshift/keys) — no admin has to mint or share credentials. Live web search is now available as a per-request [plugin](/routeshift/plugins) — opt in with a `:online` model suffix or an explicit `plugins` array and RouteShift attaches fresh search results to the prompt without your client wiring a second API. Credit accounting is now reserved before dispatch on every credits-mode path (closing a concurrent-overspend window), the [circuit breaker](/routeshift/routing) gained an optional percentage-based trip mode, and [reasoning-effort and thinking-budget controls](/routeshift/routing) became first-class routing-rule fields that also participate in the response cache. A new weekly cron flags newly-released models for human review instead of silently adding them to the catalog, so surprise auto-routing doesn't happen. Codex also published six new research-tier datasets on Hugging Face. ### New features [#new-features] * **RouteShift**: Native **SSO device-flow login** for the [`connect` CLI](/routeshift/getting-started). A teammate at a Google Workspace or Okta org runs the CLI, receives an 8-character user code, approves it in their browser through the org's real IdP, and the CLI receives a short-lived (8-hour) self-service [virtual key](/routeshift/keys) — no admin has to manually mint or share credentials, and every issuance is written to the workspace [audit log](/routeshift/team) with the SSO subject. Full RFC 8628 (OAuth 2.0 Device Authorization Grant) implementation. Provisioning is per-team via new IdP-config admin endpoints; the device flow is gated by `SSO_DEVICE_FLOW_ENABLED` and stays off until a team is onboarded. Rate limiting is keyed on the device code (not the client IP), so users behind shared or NAT'd IPs aren't falsely throttled. * **RouteShift**: New **[web search plugin](/routeshift/web-search)** for any chat completion. Opt in per request with a `:online` model suffix or an explicit `plugins: [{ id: "web", ... }]` entry, and RouteShift queries a search backend, formats the top results as a clearly labeled context block, appends them to the system prompt, and forwards to the upstream provider — the model sees titles, URLs, and snippets, and never sees a raw `plugins` field. Augmented turns are non-cacheable so time-sensitive results are never replayed, and callers who mark the plugin `required: true` get a clean `plugin_required_failed` on backend failure instead of a silently un-augmented response. See the [July 10 daily entry](/changelog/2026-07-10). * **Codex**: Six new [research-tier](/codex/data-catalog) datasets on the [Axiom AI Hugging Face organization](https://huggingface.co/axiom-ai) — [AIS Maritime](/codex/schemas/ais-maritime), [Civic Intelligence — Events Timeline](/codex/schemas/events-timeline), [OSHA Safety](/codex/schemas/osha-safety), [LEHD Commuter Flows](/codex/schemas/lehd-commuter-flows), [POI Intelligence](/codex/schemas/poi-intelligence), and [Permit Signals](/codex/schemas/permit-signals). Each is a deterministic 100K-record stratified sample in Parquet under CC-BY-4.0, shipped with a README, schema documentation, and the standard [APRS envelope](/codex/normalization-standard). See the [July 9 daily entry](/changelog/2026-07-09). * **RouteShift**: `reasoning_effort` and `thinking_budget_tokens` are now modifiable [routing-rule fields](/routeshift/routing) — a rule can dial reasoning effort or extended-thinking budget up or down per match without the client changing anything. Both fields are also part of the response cache key, so a `high`-effort call and a `low`-effort call to the same prompt no longer collide on a cache hit. * **RouteShift**: The [circuit breaker on load-balanced provider keys](/routeshift/routing) gained an optional **percentage-based trip mode** — instead of tripping on a raw count of `5xx`/`429`, a credential can be parked when its error rate crosses a threshold within a sliding window. Useful for noisy multi-region setups where a few isolated failures shouldn't take a key out of rotation. * **RouteShift**: New **model-drift detection** cron runs weekly and proposes newly-released models as *parked* [catalog entries](/routeshift/savings-and-pricing) — never auto-routed — so a human reviews and approves a new model before any traffic can land on it. Pairs with the existing weekly pricing sync. * **RouteShift**: Weekly [pricing sync](/routeshift/savings-and-pricing) coverage extended to more providers, so newly-released models and provider price drops propagate into routing decisions and analytics without manual data entry. * **RouteShift**: [Preset](/routeshift/routing) **version history** is now visible in the dashboard. Every edit to a named preset already produced an immutable snapshot; two new team-scoped read endpoints let the dashboard list past versions (newest first) and open any single revision with its model, params, system prompt, provider preferences, author, and timestamp — useful for diffing a working preset against last week's known-good version, or copying a field back after a bad edit. Cross-team lookups return the same `preset_not_found` response as missing presets. See the [July 10 daily entry](/changelog/2026-07-10). ### Updates [#updates] * **RouteShift**: [Credit reservation](/routeshift/billing) now happens *before* the upstream request dispatches on every credits-mode path. Previously the pre-flight check was advisory, so two concurrent large requests from the same key could both pass, each read a stale balance, and dispatch — leaving the workspace briefly negative. Reservations are now the source of truth: concurrent requests contend on the reservation, and one is rejected cleanly instead of both completing on borrowed balance. * **RouteShift**: Response cache invalidation on provider-key rotation. When you rotate an upstream credential in [Providers](/routeshift/providers), cached responses tied to the old credential are dropped, so a rotated-out key can never resurface content on a cache hit. * **RouteShift**: [Billing-mode changes](/routeshift/billing) (switching between credits mode and the standard 3% savings-share) now invalidate the cached billing-mode read at the same time, so a mode change takes effect on the next request instead of the next cache refresh. * **RouteShift**: Dispute reinstatement is now symmetric — a Stripe chargeback dispute that resolves in your favor restores credits to the same ledger balance the debit originally came from, matching the debit path exactly. No lost or duplicated credits when a disputed charge reverses. * **RouteShift**: An **operator-funded prompt-optimizer** spend cap now bounds RouteShift's own [Optimize](/routeshift/optimize) analysis calls per workspace, so the optimizer can't drift into an expensive loop against a single tenant. * **RouteShift**: Sentry alert on missing-pricing gaps outside credits mode — if a request lands on a model whose [pricing catalog](/routeshift/savings-and-pricing) entry is missing, on-call sees it immediately instead of silent zero-cost accounting. ### Fixes [#fixes] * **RouteShift**: Streaming settle-failure no longer refunds already-delivered content. If the credit-settlement write failed *after* tokens were already streamed to the client, the previous code would refund the full request as if it hadn't been served. Settlement now distinguishes delivery from settlement so a partial failure only refunds what wasn't received. * **RouteShift**: [Auto-topup](/routeshift/billing) webhook backfill for a worker-crash window. If the auto-topup worker crashed between charging Stripe and stamping the workspace, the next run could double-charge or skip topups entirely. Backfill now reconciles Stripe against ledger state on restart and stamps the cooldown timestamp so no window is retried twice. * **RouteShift**: Cache-write TTL bug fixed — some [response-cache](/routeshift/observability) writes were landing with a 1-hour TTL instead of the configured value, causing early misses on long-lived entries. Writes now use the configured TTL end-to-end. * **RouteShift**: `custom`-condition [routing rules](/routeshift/routing) now fail closed. Previously a `custom`-condition rule with a malformed or missing predicate was silently matching every request (fail-open); it now rejects the malformed rule at save time and never matches at runtime. * **RouteShift**: `keyHasReadScope` gate closes a [usage and generation-lookup](/routeshift/observability) scope-bypass. A read-scoped [virtual key](/routeshift/keys) can no longer reach admin-usage endpoints intended for full-scope keys. * **RouteShift**: Team-invitation accept race fixed — accepting a [team](/routeshift/team) invitation twice (double-click, refresh) can no longer produce a duplicate membership row or wedge the accept flow. * **RouteShift**: `connect --tool claude-code` config-safety fix — the local [connect CLI](/routeshift/getting-started) no longer overwrites an existing tool config file when re-run against the same tool; it merges or prompts instead. * **RouteShift**: [Preset](/routeshift/presets) write responses (create, update, disable, delete) now report an explicit `proxy_cache_invalidated` flag — and, on failure, `proxy_cache_error: "proxy_cache_invalidation_failed"` plus `cache_ttl_seconds`. The database write is still committed, but callers now see when the proxy's preset cache invalidation didn't land, instead of the previous silent success. See the [July 10 daily entry](/changelog/2026-07-10). * **Codex**: The Chicago **building-inspection records** dataset now carries the correct `source_uri` on every row — a backfill previously left 3,671 rows with an empty source URL and 628 more with no envelope at all; all 4,299 rows now point at their real Chicago Socrata source, and the daily cron that keeps this dataset current has been restored. See the [July 9 daily entry](/changelog/2026-07-09). * **Overwatch**: The analytical charts on [Forecasts](/overwatch/api/forecasts), [Estimates](/overwatch/api/estimates), [Fleet](/overwatch/api/fleet) (age histogram and age-trend), [Berth](/overwatch/api/berth) utilization, seasonality panels, the ownership-graph visualizations, and the Locus score-history panel on the [locus-validation](/locus/scoring-conventions) view render cleanly during layout transitions. Three earlier passes had guarded the terminal-panel charts against a Recharts zero-dimension render warning, but ten chart surfaces elsewhere in the app were still unguarded and could briefly render at negative width or height (or flash a console warning) whenever their container measured before layout settled. Every chart surface is now guarded uniformly, and a repository-wide check prevents new charts from regressing. See the [July 9 daily entry](/changelog/2026-07-09). * **Layer**: **Google sign-in restored.** New and returning users signing in through Google Workspace via [Auth0 Universal Login](/layer/getting-started) reach the Layer app cleanly again — an internal token-verification mismatch had been rejecting valid Google magic-link callbacks with a "one-time token not found" error. Existing sessions were unaffected; no action is required on your part. * **Locus**: The nightly [HMDA multifamily](/locus/scoring-conventions) ingest is safe against an upstream CFPB API regression. The public HMDA endpoint silently stopped honoring the `property_types=3` server-side filter on 2026-07-01, which would have pulled 15–45× the expected volume per state into the multifamily loan-records table on the next scheduled run. The collector now filters multifamily loans client-side, enforces a per-state ceiling that fails loudly instead of over-ingesting, and streams the CSV response so a full state pull can't exhaust worker memory. As a bonus, rows now carry the correct `property_type` value they'd been silently missing since the loader was written, so multifamily and construction loan counts in the derived aggregates are populated for the first time. See the [July 10 daily entry](/changelog/2026-07-10). # July 11, 2026 (/changelog/2026-07-11) ## Paid plans are live [#paid-plans-are-live] Layer now supports paid subscriptions. You can upgrade to Starter, Growth, or Scale directly from the new **Settings → Billing** page — pick a plan, choose monthly or annual billing, and check out without leaving the app. Once subscribed, the same page shows your current plan and lets you manage your payment method, switch plans, or cancel at any time through a self-service billing portal. If you visited the pricing page before today and selected a plan, Layer remembers your choice and picks up right where you left off during sign-up. # July 17, 2026 (/changelog/2026-07-17) ## Status page now covers trade release feeds and reads freshness cadence-aware [#status-page-now-covers-trade-release-feeds-and-reads-freshness-cadence-aware] The [status page](/overwatch/status-page) now surfaces two additional ingestion feeds alongside AIS and PSIX — **USACE Waterborne Commerce (WCSC)** and **US Census trade releases**, both on a monthly cadence — so users can see at a glance whether the monthly trade data behind [port cargo](/overwatch/methodology/cargo-validation) analytics is current. Feed freshness is also now evaluated cadence-aware. Daily, weekly, and monthly feeds previously shared a single row window with high-frequency AIS ingestion and could age out of the returned set, showing as **NEVER RAN** even when running on schedule. Each cadence bucket now uses its own lookback window, so slower feeds report their true state. # July 18, 2026 (/changelog/2026-07-18) ## More reliable APRS compliance checks [#more-reliable-aprs-compliance-checks] The automated [APRS compliance gate](/codex/envelope-coverage) now handles transient API cache issues gracefully instead of failing with an opaque error. Previously, a stale schema cache could cause the shape-check to report a false failure after new tables were added. The gate now detects this condition, surfaces a clear diagnostic, and self-recovers — so compliance validation stays accurate even during schema changes. # Week of July 12–18, 2026 (/changelog/2026-07-19-weekly) ## This week at a glance [#this-week-at-a-glance] A heavy ship week across all five products — over a hundred merged PRs. Layer shipped a rebuilt console dashboard and a database hardening pass, Overwatch published its first port commodity contract and a seasonal grain forecast, Locus landed a parcel pilot contract, a land-face publish path, and replayable score evidence alongside a collector reliability series, Codex delivered its reviewed Graph governance tranche, and RouteShift closed a security review on last week's SSO device flow. ### New features [#new-features] * **Layer**: The **console dashboard v2** — KPI cards that only report numbers backed by real data, trend sparklines, period-aware benchmark annualization, and action insights. Integration connectors now render real brand logos, and the [browser extension](/layer/browser-extension) got unified Discovery branding with an honest privacy disclosure. * **Overwatch**: **Port commodity contract v1** — a published contract for port-level commodity flows, joined by point-in-time **weather residual** and **cargo mass residual** contracts and canonical port-identity consumers across the platform. * **Overwatch**: An **ENSO/ONI-aware seasonal grain-export forecast** — seasonal export projections that now account for El Niño/La Niña cycle state. See the [forecasts API](/overwatch/api/forecasts). * **Locus**: A fail-closed **parcel pilot contract**, a state-scale **land-face publish path**, and **replayable aggregate score evidence** — composite scores now persist the inputs needed to reproduce them. See [scoring conventions](/locus/scoring-conventions). * **Codex**: The reviewed **Codex Graph governance and packaging tranche** — hardened evaluation splits, KGC inputs, and a schema quickstart, with signoff evidence now bound to review domains. ### Updates [#updates] * **Layer**: Optimization savings are now computed from real inputs end-to-end — the dashboard's savings figures are driven by actual usage and spend data. * **Overwatch**: The [status page](/overwatch/status-page) now covers monthly **USACE Waterborne Commerce** and **US Census trade release** feeds alongside AIS and PSIX, and evaluates feed freshness per-cadence so daily, weekly, and monthly feeds no longer falsely surface as **NEVER RAN** when running on schedule. See the [July 17 daily entry](/changelog/2026-07-17). * **Codex**: The [APRS compliance gate](/codex/envelope-coverage) now handles transient schema-cache issues gracefully instead of failing with an opaque error, so validation stays accurate during schema changes. See the [July 18 daily entry](/changelog/2026-07-18). * **RouteShift**: The shared **prompt-cache isolation policy** is decided and documented — team-keyed response caching stays separate from provider-managed prompt caches, with explicit opt-in, credential-boundary, and rollback gates. ### Fixes [#fixes] * **RouteShift**: A multi-model security review of last week's SSO device-flow login landed a post-merge fix batch: discovery-doc endpoints are now HTTPS-only (closing an XSS), the device-token endpoint has a per-IP ceiling (closing a DoS), unauthenticated OAuth routes cap request bodies at 64KB (closing an OOM), Okta token exchange falls back to `client_secret_basic`, `email_verified` stays fail-closed on key minting, and the audit trail records superseded keys. * **Layer**: A database performance and correctness pass — 86 RLS policies wrapped for initplan caching, 48 service policies scoped to `service_role`, permissive-policy overlaps consolidated, and a duplicate index dropped. The GitHub commit sync also got atomic batches and guarded status transitions, and the extension now rejects retired telemetry hostnames. * **Overwatch**: Trade-release and PSIX ingestion durability — releases resume off durable state with a bounded finalize timeout, only an authoritative owner failure can terminalize a Scout run, claimed ingestion-log identities are preserved, and GFW data is fenced to research-only use. * **Locus**: FAF5 lineage and trace replay hardening, a self-activating Bright Data residential proxy for the YouTube council collector, three chronic-dead sources disabled, and Legistar collectors now require variance-run evidence. * **Codex**: Permit, entity-resolution, geospatial, and temporal evidence hardening across the release pipeline, plus release-audit intake for permits and sealed-snapshot coverage requirements. The next update will land in the [July 19–25 weekly recap](/changelog/2026-07-25-weekly). # Week of July 19–25, 2026 (/changelog/2026-07-25-weekly) This is a historical release record. Launch-supported chokepoint confirmation is currently AIS-only; Sentinel catalog coverage does not detect vessels or confirm transits. See the [current methodology](/overwatch/methodology/chokepoint-transits). ## This week at a glance [#this-week-at-a-glance] 115 user-facing PRs merged across Layer, Overwatch, Locus, RouteShift, Codex, and Invest. ### New features [#new-features] * **Layer**: LiteLLM pricing, CI cost controls, landing viz (LAY-313/712/718) ([#211](https://github.com/smynkr/axiomlayer/pull/211)) * **Layer**: FOCUS ledger, AI passports, SCuBA import, privacy pilot (LAY-695 LAY-694) ([#206](https://github.com/smynkr/axiomlayer/pull/206)) * **Layer**: agent registry, remediation, calibration & freshness (LAY-698) ([#204](https://github.com/smynkr/axiomlayer/pull/204)) * **Layer**: link the shared docs site from the Layer footer (LAY-707) ([#205](https://github.com/smynkr/axiomlayer/pull/205)) * **Overwatch**: integrate and harden Launch 4.0 on current main ([#292](https://github.com/smynkr/axiom-overwatch/pull/292)) * **Overwatch**: ingest Sentinel-2 optical chokepoint scene catalog (AXO-464) ([#198](https://github.com/smynkr/axiom-overwatch/pull/198)) * **Overwatch**: identity-consistency graph risk feature ([#186](https://github.com/smynkr/axiom-overwatch/pull/186)) * **Overwatch**: AIS-behavioral ML load-state predictor as hydrostatics cross-check (AXO-469) ([#195](https://github.com/smynkr/axiom-overwatch/pull/195)) * **Overwatch**: AIS communication-fault prefilter ([#187](https://github.com/smynkr/axiom-overwatch/pull/187)) * **Overwatch**: @axiom/ftm package + ftm JSONB on 3 producers (AXL-229) ([#20](https://github.com/smynkr/axiom-overwatch/pull/20)) * **Overwatch**: azimuth-shift (Doppler) compensation for SAR-AIS matching (AXO-463) ([#199](https://github.com/smynkr/axiom-overwatch/pull/199)) * **Locus**: make score explanations truthful and usable ([#299](https://github.com/smynkr/axiom-locus/pull/299)) * **Locus**: add calibrated Valhalla drive accessibility ([#196](https://github.com/smynkr/axiom-locus/pull/196)) * **RouteShift**: preserve native provider tool turns (RSH-68) ([#125](https://github.com/smynkr/RouteShift/pull/125)) * **RouteShift**: add Gemini thinking levels and reasoning telemetry ([#148](https://github.com/smynkr/RouteShift/pull/148)) * **RouteShift**: enforce auto-topup hard ceilings (RSH-92) ([#140](https://github.com/smynkr/RouteShift/pull/140)) * **RouteShift**: link docs.axiomancer.io from landing nav and footer ([#150](https://github.com/smynkr/RouteShift/pull/150)) * **Invest**: reasoning-trace observability — capture, persist, score extended thinking (TRD-863 WS5) ([#568](https://github.com/smynkr/invest/pull/568)) * **Invest**: trade-quality dial + fail-closed daily entry budget + capital veto (TRD-863 WS2) ([#567](https://github.com/smynkr/invest/pull/567)) * **Invest**: extended reasoning walls + timeout-chain alignment + no deep→fast fallback ([#566](https://github.com/smynkr/invest/pull/566)) * **Invest**: submit-time staleness re-check for slow decisions ([#565](https://github.com/smynkr/invest/pull/565)) * **Invest**: Aliyun rung-3 GLM backup fallback + qwen3.8-max-preview eval aliases ([#543](https://github.com/smynkr/invest/pull/543)) ### Updates [#updates] * **Layer**: wrap helpers + consolidate permissive policies on new governance tables (LAY-709) ([#209](https://github.com/smynkr/axiomlayer/pull/209)) * **Layer**: bind subject\_asset\_id to caller org in ingest\_security\_event (LAY-710) ([#208](https://github.com/smynkr/axiomlayer/pull/208)) * **Overwatch**: AXO-465: Cost-routing cascade for LLM extraction pipeline ([#197](https://github.com/smynkr/axiom-overwatch/pull/197)) * **Overwatch**: STS/loitering detector: enforce exact GFW encounter thresholds (AXO-454) ([#193](https://github.com/smynkr/axiom-overwatch/pull/193)) * **Overwatch**: refresh axiomoverwatch.io metrics to live 2026-07-19 inventory ([#294](https://github.com/smynkr/axiom-overwatch/pull/294)) * **Overwatch**: Codex Live: integrate governed ingestion and health observability ([#296](https://github.com/smynkr/axiom-overwatch/pull/296)) * **Overwatch**: add Axiom Docs link to Overwatch Resources column ([#295](https://github.com/smynkr/axiom-overwatch/pull/295)) * **Locus**: AXL-157: add canonical renter filters to Discover ([#303](https://github.com/smynkr/axiom-locus/pull/303)) * **Locus**: AXL-391: formalize range pagination on scalar-jsonb RPCs ([#290](https://github.com/smynkr/axiom-locus/pull/290)) * **Locus**: AXL-440: make metro overview movement truthful ([#301](https://github.com/smynkr/axiom-locus/pull/301)) * **Locus**: link to shared docs site from Product column ([#305](https://github.com/smynkr/axiom-locus/pull/305)) * **RouteShift**: Add first-run quick start to Overview ([#133](https://github.com/smynkr/RouteShift/pull/133)) * **RouteShift**: RSH-126: bounded service-tier intent ([#149](https://github.com/smynkr/RouteShift/pull/149)) * **RouteShift**: Polish dashboard and landing interactions ([#134](https://github.com/smynkr/RouteShift/pull/134)) * **RouteShift**: RSH-128: fail-closed data residency routing ([#147](https://github.com/smynkr/RouteShift/pull/147)) * **RouteShift**: RSH-129: isolate untrusted web search results ([#143](https://github.com/smynkr/RouteShift/pull/143)) * **Codex**: P2 remediation from 3-lane adversarial review (source types, family consistency, baseline scores) ([#101](https://github.com/smynkr/axiomcodex/pull/101)) * **Codex**: envelope completeness gate (AXC-333) + benchmark derivative-spec (AXC-314) ([#100](https://github.com/smynkr/axiomcodex/pull/100)) * **Invest**: TRD-805 bound FanOutPanel shadow backlog ([#560](https://github.com/smynkr/invest/pull/560)) * **Invest**: TRD-816 harden chaos isolation and real-native accounting ([#557](https://github.com/smynkr/invest/pull/557)) * **Invest**: TRD-793 make terminal retries fair and shutdown-safe ([#551](https://github.com/smynkr/invest/pull/551)) * **Invest**: TRD-807 harden operator acceptance contracts ([#550](https://github.com/smynkr/invest/pull/550)) * **Invest**: TRD-819 harden dormant Azure and Haiku paths ([#549](https://github.com/smynkr/invest/pull/549)) * **Invest**: TRD-809 harden shared-signal recovery and writer lifecycle ([#553](https://github.com/smynkr/invest/pull/553)) * **Invest**: TRD-810 harden research evidence and cache semantics ([#552](https://github.com/smynkr/invest/pull/552)) * **Invest**: Trader Live wave 4: harden replay, risk, monitoring, and SSE ([#541](https://github.com/smynkr/invest/pull/541)) * **Invest**: Trader Live: close six correctness and durability gaps ([#539](https://github.com/smynkr/invest/pull/539)) * **Invest**: TRD-461: stamp decision policy epochs ([#527](https://github.com/smynkr/invest/pull/527)) * **Invest**: TRD-701: make restore drills fail closed ([#513](https://github.com/smynkr/invest/pull/513)) * **Invest**: TRD-466: add shadow experiment preregistration harness ([#526](https://github.com/smynkr/invest/pull/526)) * **Invest**: TRD-463: add shadow calibration receipt ([#525](https://github.com/smynkr/invest/pull/525)) * **Invest**: TRD-650: fully retire screener publisher ([#524](https://github.com/smynkr/invest/pull/524)) * **Invest**: TRD-184: persist stale provider rejections ([#503](https://github.com/smynkr/invest/pull/503)) * **Invest**: TRD-684: breadcrumb expired OCP reservation guards ([#502](https://github.com/smynkr/invest/pull/502)) * **Invest**: TRD-517: record mixed CF fallback qualification proof ([#479](https://github.com/smynkr/invest/pull/479)) * **Invest**: TRD-700: define live execution canary policy ([#477](https://github.com/smynkr/invest/pull/477)) ### Fixes [#fixes] * **Layer**: gate + test wiki-mirror Worker, fix Spend silent failures (LAY-716 LAY-719 LAY-720) ([#216](https://github.com/smynkr/axiomlayer/pull/216)) * **Layer**: land LAY-643/645/660 extension telemetry + offboarding hardening (revives #195) ([#215](https://github.com/smynkr/axiomlayer/pull/215)) * **Layer**: address review P2s from PR #211 gauntlet (LAY-313/630/712/718) ([#212](https://github.com/smynkr/axiomlayer/pull/212)) * **Layer**: reconcile devices.lifecycle\_state for deployed devices (LAY-711) ([#210](https://github.com/smynkr/axiomlayer/pull/210)) * **Layer**: repair prod is\_org\_admin() drift so admin-write RLS grants (LAY-708) ([#207](https://github.com/smynkr/axiomlayer/pull/207)) * **Overwatch**: address adversarial review findings — URL sanitizer, clock-skew guard, reclaim reserve ([#304](https://github.com/smynkr/axiom-overwatch/pull/304)) * **Overwatch**: split claim\_ingestion\_deliveries OR into two index-efficient phases ([#303](https://github.com/smynkr/axiom-overwatch/pull/303)) * **Overwatch**: redact Equasis session cookie values from worker logs ([#302](https://github.com/smynkr/axiom-overwatch/pull/302)) * **Overwatch**: stop two Sentry noise sources on the live map ([#299](https://github.com/smynkr/axiom-overwatch/pull/299)) * **Overwatch**: AXO-167 attribution on vessel-flag temporal\_edges triggers ([#203](https://github.com/smynkr/axiom-overwatch/pull/203)) * **Overwatch — historical code report; [SAR detection is not launch-supported](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: suppress small (\<60m) SAR contacts from dark-vessel scoring & writes ([#188](https://github.com/smynkr/axiom-overwatch/pull/188)) * **Overwatch**: Loop-15 quick wins — dbt close-gate evidence + temporal-decay contract (AXO-428, AXO-429) ([#161](https://github.com/smynkr/axiom-overwatch/pull/161)) * **Overwatch**: suppress recharts/abort/fallback Sentry noise ([#293](https://github.com/smynkr/axiom-overwatch/pull/293)) * **Overwatch**: correct ingested\_at semantics in HMDA envelope backfill ([#204](https://github.com/smynkr/axiom-overwatch/pull/204)) * **Overwatch**: use admin client for overview AIS count ([#297](https://github.com/smynkr/axiom-overwatch/pull/297)) * **Overwatch**: stagger equasis-extraction-canary cron off minute 17 ([#298](https://github.com/smynkr/axiom-overwatch/pull/298)) * **Locus**: repair AXL-403 Deck overlay constructor crash ([#297](https://github.com/smynkr/axiom-locus/pull/297)) * **Locus**: harden cell\_score\_deltas matview ACL — revoke write bits, grant SELECT ([#309](https://github.com/smynkr/axiom-locus/pull/309)) * **Locus**: make profile comparison reliable and interactive ([#298](https://github.com/smynkr/axiom-locus/pull/298)) * **Locus**: restore authenticated cell search ([#304](https://github.com/smynkr/axiom-locus/pull/304)) * **Locus**: resolve four Locus findings ([#307](https://github.com/smynkr/axiom-locus/pull/307)) * **RouteShift**: normalize PDF bytes for Node 26 (RSH-125) ([#126](https://github.com/smynkr/RouteShift/pull/126)) * **RouteShift**: remove redundant model quick picks ([#132](https://github.com/smynkr/RouteShift/pull/132)) * **Invest**: boot cache-truth convergence guard — verified reconciliation before cache authority; bounded halt reasons ([#569](https://github.com/smynkr/invest/pull/569)) * **Invest**: signal-admission drop receipts + status-file age gate + confidence-coercion warning ([#564](https://github.com/smynkr/invest/pull/564)) * **Invest**: witness-qualified equity late re-anchor; decouple opening witness from book truth ([#563](https://github.com/smynkr/invest/pull/563)) * **Invest**: close non-jury late spend windows (TRD-853) ([#558](https://github.com/smynkr/invest/pull/558)) * **Invest**: Phase-0 ruin-fence backstop — automated exits can no longer strand naked shorts ([#556](https://github.com/smynkr/invest/pull/556)) * **Invest**: derive escalation tool budget; page on repeated confirm\_all starvation ([#555](https://github.com/smynkr/invest/pull/555)) * **Invest**: kimi-review slice 1 — startup fill re-sync, feed-router age-out, canonical venue netting ([#536](https://github.com/smynkr/invest/pull/536)) * **Invest**: concentration-gate proposal seam must not use raw notional as candidate risk ([#554](https://github.com/smynkr/invest/pull/554)) * **Invest**: close late jury spend settlement window (TRD-831) ([#548](https://github.com/smynkr/invest/pull/548)) * **Invest**: close Trader Live acceptance gaps (TRD-837) ([#546](https://github.com/smynkr/invest/pull/546)) * **Invest**: dashboard wiring — real P\&L, honest strategy stats, correct cards, collapsible chart ([#545](https://github.com/smynkr/invest/pull/545)) * **Invest**: sampling-aware outcome-enricher coverage rule ([#544](https://github.com/smynkr/invest/pull/544)) * **Invest**: remove backticks from unquoted-heredoc SQL comments in session monitor ([#542](https://github.com/smynkr/invest/pull/542)) * **Invest**: expiry auto-close without a mark, equity notional, artifact provenance ([#537](https://github.com/smynkr/invest/pull/537)) * **Invest**: stop fabricating direction in darkpool + options-flow signals ([#535](https://github.com/smynkr/invest/pull/535)) * **Invest**: deploy timeout budget, drift-check creds fail loud, placebo tests out ([#534](https://github.com/smynkr/invest/pull/534)) * **Invest**: IB snapshotters recover the PG session after a poll failure ([#533](https://github.com/smynkr/invest/pull/533)) * **Invest**: keep console SSE push alive across stream recycle + echarts XSS bump ([#532](https://github.com/smynkr/invest/pull/532)) * **Invest**: kimi-review batch 1 — fail-safe env/int parsing + visible lifecycle reconcile failures ([#529](https://github.com/smynkr/invest/pull/529)) * **Invest**: switch canary to OpenAI gpt-5.4-mini while NeuralWatt billing-limited ([#540](https://github.com/smynkr/invest/pull/540)) * **Invest**: venue-mirror collapse in close guard, position-truth error detail, triangle unit decoupling ([#528](https://github.com/smynkr/invest/pull/528)) * **Invest**: close live preflight false-green paths ([#519](https://github.com/smynkr/invest/pull/519)) * **Invest**: correct operator health documentation ([#521](https://github.com/smynkr/invest/pull/521)) * **Invest**: require confirmation for decide-now proposals ([#523](https://github.com/smynkr/invest/pull/523)) * **Invest**: cache loop-breaker control-plane knob ([#522](https://github.com/smynkr/invest/pull/522)) * **Invest**: reserve executable opening debit before approval ([#515](https://github.com/smynkr/invest/pull/515)) * **Invest**: harden Graphiti client auth and repair wiki drift ([#511](https://github.com/smynkr/invest/pull/511)) * **Invest**: harden launchd auth and repo-own order-flow watchdog ([#510](https://github.com/smynkr/invest/pull/510)) * **Invest**: accept as\_of kwarg in replay retriever stub ([#506](https://github.com/smynkr/invest/pull/506)) * **Invest**: exclude TRD-203 example fixtures by default ([#504](https://github.com/smynkr/invest/pull/504)) * **Invest**: reject crossed collar equity quotes \[TRD-532] ([#501](https://github.com/smynkr/invest/pull/501)) * **Invest**: truthfully filter scanner opening trades ([#482](https://github.com/smynkr/invest/pull/482)) * **Invest**: harden post-open readiness paging \[TRD-597] ([#470](https://github.com/smynkr/invest/pull/470)) * **Invest**: canonicalize IB option venue identity ([#451](https://github.com/smynkr/invest/pull/451)) # Week of July 26 – August 1, 2026 (/changelog/2026-08-01-weekly) This is a historical release record. Launch-supported chokepoint confirmation is currently AIS-only; Sentinel catalog coverage does not detect vessels or confirm transits. See the [current methodology](/overwatch/methodology/chokepoint-transits). ## This week at a glance [#this-week-at-a-glance] 319 user-facing PRs merged across Layer, Overwatch, Locus, RouteShift, Codex, and Invest. ### New features [#new-features] * **Layer**: add admin-client membership guard ratchet (LAY-749) ([#246](https://github.com/smynkr/axiomlayer/pull/246)) * **Layer**: add extension API key controls (LAY-740) ([#236](https://github.com/smynkr/axiomlayer/pull/236)) * **Layer**: privacy-first Sentry + PostHog observability (LAY-760) ([#228](https://github.com/smynkr/axiomlayer/pull/228)) * **Layer**: add x\_PriceBasis and ground the contract-withholding rationale (LAY-734) ([#225](https://github.com/smynkr/axiomlayer/pull/225)) * **Layer**: make spend surfaces cost-basis aware (LAY-734) ([#220](https://github.com/smynkr/axiomlayer/pull/220)) * **Layer**: one-shot RouteShift cost-basis backfill script (LAY-728) ([#218](https://github.com/smynkr/axiomlayer/pull/218)) * **Overwatch**: advance Overwatch Live code-safe acceptance tranche ([#333](https://github.com/smynkr/axiom-overwatch/pull/333)) * **Overwatch**: schedule the weekly CBP ingest with a per-form freshness gate ([#380](https://github.com/smynkr/axiom-overwatch/pull/380)) * **Overwatch**: Task 4 artifact decision + Task 7 envelope/RLS/crosscheck coverage ([#381](https://github.com/smynkr/axiom-overwatch/pull/381)) * **Overwatch**: AXO-715 migration-version collision guard ([#371](https://github.com/smynkr/axiom-overwatch/pull/371)) * **Overwatch**: AXO-714 unified pipeline-freshness monitor + h3\_coverage\_estimate ([#370](https://github.com/smynkr/axiom-overwatch/pull/370)) * **Overwatch**: ingest CBP CF-1400/1401 vessel entrance/clearance reports ([#347](https://github.com/smynkr/axiom-overwatch/pull/347)) * **Overwatch**: SAR-hybrid dark-fleet verification — GFW cross-val + per-pixel detection (F1–F5 fixed) ([#169](https://github.com/smynkr/axiom-overwatch/pull/169)) * **Locus**: AXL-519 OSHA PSM citations table (APRS + RLS) ([#391](https://github.com/smynkr/axiom-locus/pull/391)) * **Locus**: add building\_permits chunk\_id backfill engine (AXC-372) ([#382](https://github.com/smynkr/axiom-locus/pull/382)) * **Locus**: orphan reaper delete lane — age-guarded, double-flagged, fail-loud ([#390](https://github.com/smynkr/axiom-locus/pull/390)) * **Locus**: dry-run orphaned-R2 archive reaper (report only) ([#389](https://github.com/smynkr/axiom-locus/pull/389)) * **Locus**: AXL-517 add uspto\_patent\_grants SourceSpec + LoaderRunResult emission ([#388](https://github.com/smynkr/axiom-locus/pull/388)) * **Locus**: add dataset card slug linkage to data\_source\_catalog (AXC-264) ([#380](https://github.com/smynkr/axiom-locus/pull/380)) * **Locus**: add training example emission with negative examples (AXC-256, AXC-258) ([#379](https://github.com/smynkr/axiom-locus/pull/379)) * **Locus**: add label provenance emission to civic extractor (AXC-260) ([#378](https://github.com/smynkr/axiom-locus/pull/378)) * **Locus**: add extraction trace emission to permit extractor (AXC-263) ([#377](https://github.com/smynkr/axiom-locus/pull/377)) * **Locus**: bridge LoaderRunResult to codex ingestion manifests (AXC-265) ([#376](https://github.com/smynkr/axiom-locus/pull/376)) * **Locus**: integrate GSA lease escalation clauses (2026-FOI-01417) ([#308](https://github.com/smynkr/axiom-locus/pull/308)) * **Locus**: APRS coverage report persistence + scheduled live-audit workflow ([#341](https://github.com/smynkr/axiom-locus/pull/341)) * **Locus**: ship Locus Live KG decision and demo contracts ([#310](https://github.com/smynkr/axiom-locus/pull/310)) * **RouteShift**: RSH-151 + RSH-152 admin config CRUD for classifier and guardrails ([#183](https://github.com/smynkr/RouteShift/pull/183)) * **RouteShift**: RSH-135 async LLM classifier dimensions ([#182](https://github.com/smynkr/RouteShift/pull/182)) * **RouteShift**: RSH-139 pre-dispatch guardrail scanning ([#181](https://github.com/smynkr/RouteShift/pull/181)) * **RouteShift**: RSH-88 Phase 1 — dual-read v3 path, KEK adapter injection, DEK cache ([#174](https://github.com/smynkr/RouteShift/pull/174)) * **RouteShift**: RSH-88 Phase 1 — envelope codec, KEK adapter, schema foundation ([#173](https://github.com/smynkr/RouteShift/pull/173)) * **RouteShift**: RSH-134 Phase 3 — worst-case reservation + atomic cascade settlement ([#172](https://github.com/smynkr/RouteShift/pull/172)) * **RouteShift**: RSH-85 Phase 1 — pure shadow-routing contract + disabled control plane ([#170](https://github.com/smynkr/RouteShift/pull/170)) * **RouteShift**: wire the quality cascade into the served path, gated on a billing ack (RSH-134 step 2) ([#168](https://github.com/smynkr/RouteShift/pull/168)) * **RouteShift**: wire the quality cascade into the served path, gated on a billing ack (RSH-134 step 2) ([#166](https://github.com/smynkr/RouteShift/pull/166)) * **RouteShift**: expose savings on /admin/usage/by-identity (RSH-137) ([#165](https://github.com/smynkr/RouteShift/pull/165)) * **RouteShift**: surface aggregate actual cost on QualityCascadeResult (RSH-134 step 1) ([#163](https://github.com/smynkr/RouteShift/pull/163)) * **Codex**: APRS->HF staging transform + reclassify 3 dead-endpoint feeds to manual\_only ([#124](https://github.com/smynkr/axiomcodex/pull/124)) * **Codex**: bind text\_view\_version and dataset\_card to training exports (AXC-257, AXC-264) ([#123](https://github.com/smynkr/axiomcodex/pull/123)) * **Codex**: permit Socrata canaries, customer-portal prototype, wiki reconciliation ([#122](https://github.com/smynkr/axiomcodex/pull/122)) * **Codex**: add APRS and training foundations ([#98](https://github.com/smynkr/axiomcodex/pull/98)) * **Codex**: add governed training data contracts ([#97](https://github.com/smynkr/axiomcodex/pull/97)) * **Codex**: add training provenance and reproducibility foundations ([#96](https://github.com/smynkr/axiomcodex/pull/96)) * **Invest**: add native cache recovery and quarantine contracts ([#703](https://github.com/smynkr/invest/pull/703)) * **Invest**: add Nautilus cache admission probe (Part of TRD-1075) ([#694](https://github.com/smynkr/invest/pull/694)) * **Invest**: name the broker-open/cache-absent position-truth divergence (detector) ([#689](https://github.com/smynkr/invest/pull/689)) * **Invest**: isolate Nautilus cache Redis configuration (Part of TRD-1074) ([#692](https://github.com/smynkr/invest/pull/692)) * **Invest**: complete proposal accounting and PAPER rotation evidence ([#685](https://github.com/smynkr/invest/pull/685)) * **Invest**: TRD-972 — pre-restart order-state preflight + last-moment drain for mid-RTH deploys ([#649](https://github.com/smynkr/invest/pull/649)) * **Invest**: two-stage sizing capture, no\_action\_class, lighter traces (+ dual-review fix round) ([#607](https://github.com/smynkr/invest/pull/607)) * **Invest**: Layer-2 responder on-box systemd deployment + dead-man liveness ([#592](https://github.com/smynkr/invest/pull/592)) * **Invest**: NeuralWatt spend estimator (visibility-only) + runaway guard — no cap on normal use ([#582](https://github.com/smynkr/invest/pull/582)) ### Updates [#updates] * **Layer**: add concurrency & git discipline invariants ([#250](https://github.com/smynkr/axiomlayer/pull/250)) * **Overwatch**: AXO-421: harden legacy R2 archive rollback safety ([#340](https://github.com/smynkr/axiom-overwatch/pull/340)) * **Overwatch**: 6-PR ticket gauntlet — AXO-453, AXO-214, AXO-479, AXO-421, AXC-369, Overwatch Live tranche ([#385](https://github.com/smynkr/axiom-overwatch/pull/385)) * **Overwatch**: Add governed IRS transition candidate outbox ([#373](https://github.com/smynkr/axiom-overwatch/pull/373)) * **Overwatch**: AXO-672: bound live-map fallback diagnostics ([#339](https://github.com/smynkr/axiom-overwatch/pull/339)) * **Overwatch**: AXO-681: restore and harden dark-event archive RPC ([#338](https://github.com/smynkr/axiom-overwatch/pull/338)) * **Overwatch**: AXO-676: remove exact counts from viewport pagination ([#337](https://github.com/smynkr/axiom-overwatch/pull/337)) * **Overwatch**: checkpoint confirmed production mutations ([#331](https://github.com/smynkr/axiom-overwatch/pull/331)) * **Overwatch**: checkpoint Overwatch Live production acceptance ([#329](https://github.com/smynkr/axiom-overwatch/pull/329)) * **Overwatch**: AXO-118/119/122/124/128/131/222/234 release train ([#325](https://github.com/smynkr/axiom-overwatch/pull/325)) * **Overwatch**: AXO-360: package Core cargo estimator for Edge ([#312](https://github.com/smynkr/axiom-overwatch/pull/312)) * **Overwatch**: centralize cargo visit persistence decision ([#310](https://github.com/smynkr/axiom-overwatch/pull/310)) * **Overwatch**: route visit lifecycle decisions through core ([#308](https://github.com/smynkr/axiom-overwatch/pull/308)) * **Locus**: operator-lane artifact — drop redundant archive\_log partial index ([#387](https://github.com/smynkr/axiom-locus/pull/387)) * **Locus**: publish shared infrastructure inventory ([#328](https://github.com/smynkr/axiom-locus/pull/328)) * **Locus**: regenerate Locus agent SOT ([#366](https://github.com/smynkr/axiom-locus/pull/366)) * **Locus**: close out ingestion release tranche ([#365](https://github.com/smynkr/axiom-locus/pull/365)) * **Locus**: Complete APRS ingestion health and IRS transition contract ([#362](https://github.com/smynkr/axiom-locus/pull/362)) * **Locus**: AXL-429: restore EPA ICIS-NPDES permits ingestion ([#346](https://github.com/smynkr/axiom-locus/pull/346)) * **Locus**: AXL-352: lock transit-frequency monotonicity ([#302](https://github.com/smynkr/axiom-locus/pull/302)) * **Locus**: AXL-382: harden HHS OIG Edge Function authorization ([#348](https://github.com/smynkr/axiom-locus/pull/348)) * **Locus**: AXL-502: recover national MDRS snapshot timeout ([#351](https://github.com/smynkr/axiom-locus/pull/351)) * **Locus**: AXL-418: gate clean Supabase migration bootstrap ([#344](https://github.com/smynkr/axiom-locus/pull/344)) * **Locus**: AXL-385: reconcile live Scout worker count ([#342](https://github.com/smynkr/axiom-locus/pull/342)) * **Locus**: AXL-502: ingest official MSHA MDRS weekly snapshots ([#329](https://github.com/smynkr/axiom-locus/pull/329)) * **Locus**: disable failing Scout sources with explicit containment ([#311](https://github.com/smynkr/axiom-locus/pull/311)) * **RouteShift**: fix shadow-sampling HMAC contract in RSH-85 memo (RSH-145) ([#164](https://github.com/smynkr/RouteShift/pull/164)) * **RouteShift**: design for quality-cascade wiring + Phase 3 accounting (RSH-134) ([#160](https://github.com/smynkr/RouteShift/pull/160)) * **RouteShift**: RSH-132/133 research + recover RSH-85 shadow-routing design ([#159](https://github.com/smynkr/RouteShift/pull/159)) * **Codex**: Fix Codex ingestion trust-boundary gaps ([#121](https://github.com/smynkr/axiomcodex/pull/121)) * **Codex**: add deny-default public data expansion backlog ([#120](https://github.com/smynkr/axiomcodex/pull/120)) * **Codex**: Complete governed cross-platform ingestion handoff ([#119](https://github.com/smynkr/axiomcodex/pull/119)) * **Codex**: Type-guard drain batch 8: the migration planner, the intake bounds, and the gate's own blind spot ([#115](https://github.com/smynkr/axiomcodex/pull/115)) * **Codex**: Type-guard drain batch 7: the registry, the emitter, and the label metadata ([#114](https://github.com/smynkr/axiomcodex/pull/114)) * **Codex**: Type-guard drain batch 6: the two evidence-reaching canonicalizers ([#113](https://github.com/smynkr/axiomcodex/pull/113)) * **Codex**: Type-guard drain batch 5: the freeze-side leaf, and the keys nobody was checking ([#111](https://github.com/smynkr/axiomcodex/pull/111)) * **Codex**: Calibrate the sidecar verify-peak gate to what it actually measures ([#112](https://github.com/smynkr/axiomcodex/pull/112)) * **Codex**: Type-guard drain batch 4: the forgeable-membership class, end to end ([#110](https://github.com/smynkr/axiomcodex/pull/110)) * **Codex**: Quality-gate honesty + type-guard drain batch 3 ([#109](https://github.com/smynkr/axiomcodex/pull/109)) * **Codex**: Type-guard drain batch 2: source-policy identity and public evidence allowlist ([#108](https://github.com/smynkr/axiomcodex/pull/108)) * **Codex**: Type-guard drain batch 1: forged chunk\_id family and rights-projection bypass ([#107](https://github.com/smynkr/axiomcodex/pull/107)) * **Codex**: AXC-349 AC2 (closed): capture the build environment and interpreter version ([#106](https://github.com/smynkr/axiomcodex/pull/106)) * **Codex**: AXC-349 AC2 (partial): enforce dependency pins against actual imports ([#105](https://github.com/smynkr/axiomcodex/pull/105)) * **Codex**: AXC-353 AC2: runnable PyArrow / SQL / graph loader quickstarts ([#104](https://github.com/smynkr/axiomcodex/pull/104)) * **Codex**: AXC-351: type-guard ratchet gate for isinstance trust boundaries ([#103](https://github.com/smynkr/axiomcodex/pull/103)) * **Codex**: Harden publication, family pack, and OpenSanctions intake (AXC-309/283/276) ([#95](https://github.com/smynkr/axiomcodex/pull/95)) * **Codex**: Codex Graph: harden adjudication, ER, and geospatial gates ([#86](https://github.com/smynkr/axiomcodex/pull/86)) * **Codex**: Codex Graph: harden release-read, maritime draft, and metadata gates ([#85](https://github.com/smynkr/axiomcodex/pull/85)) * **Codex**: Integrate waves 28-42, AXC-261 export-quality command, CI gates, and the 4-of-4 gauntlet fixes ([#102](https://github.com/smynkr/axiomcodex/pull/102)) * **Invest**: TRD-1009/TRD-1089/TRD-1101: add native evidence contracts ([#717](https://github.com/smynkr/invest/pull/717)) * **Invest**: TRD-1102 to TRD-1105: consolidate native session and causal authority ([#713](https://github.com/smynkr/invest/pull/713)) * **Invest**: TRD-1106: retire direct pin and expiry close writer ([#710](https://github.com/smynkr/invest/pull/710)) * **Invest**: TRD-1097: pin native Portfolio Greeks boundary ([#708](https://github.com/smynkr/invest/pull/708)) * **Invest**: retire stale per-leg combo authority ([#707](https://github.com/smynkr/invest/pull/707)) * **Invest**: centralize position identity normalization ([#706](https://github.com/smynkr/invest/pull/706)) * **Invest**: converge native combo compiler arithmetic ([#705](https://github.com/smynkr/invest/pull/705)) * **Invest**: TRD-1088: consolidate options paths on native Nautilus owners ([#702](https://github.com/smynkr/invest/pull/702)) * **Invest**: TRD-965: segment realized edge by structure ([#697](https://github.com/smynkr/invest/pull/697)) * **Invest**: TRD-1087: complete direction-classifier wiki ingest ([#698](https://github.com/smynkr/invest/pull/698)) * **Invest**: TRD-948: classify delayed order acceptance truthfully ([#696](https://github.com/smynkr/invest/pull/696)) * **Invest**: TRD-964: meter cash\_secured\_put in the concentration + regime entry gates ([#686](https://github.com/smynkr/invest/pull/686)) * **Invest**: TRD-1024/1016/1026 guard-cluster reliability design — durable critical delivery, bounded SIGTERM exit, unrepairable-class classification ([#657](https://github.com/smynkr/invest/pull/657)) * **Invest**: TRD-1017: account-scope the opening-equity witness + persist it durably ([#671](https://github.com/smynkr/invest/pull/671)) * **Invest**: TRD-1030 + TRD-1038: portable, fail-loud morning-triage launcher and deploy trusted-path allowlists ([#669](https://github.com/smynkr/invest/pull/669)) * **Invest**: TRD-1043 — upstream issue FILED as nautilus\_trader#4619 ([#677](https://github.com/smynkr/invest/pull/677)) * **Invest**: TRD-1043: pin the nautilus netting-reconciliation fail-open contract (verdict + AST/behavioural pins + wiki note) ([#668](https://github.com/smynkr/invest/pull/668)) * **Invest**: external-operator (Hermes) readiness — delete stale briefings, onboarding runbook, wiki fixes ([#653](https://github.com/smynkr/invest/pull/653)) * **Invest**: TRD-998 — root-cause the BAG leg-fill index:order\_position mint seam (remediation deferred to TRD-1009) ([#645](https://github.com/smynkr/invest/pull/645)) * **Invest**: TRD-1013 design — reconciliation leg-on-BAG orders-row fidelity (DRAFT, gauntlet owed) ([#639](https://github.com/smynkr/invest/pull/639)) * **Invest**: TRD-993 — harden Linear auto-close, mandate Part-of references ([#635](https://github.com/smynkr/invest/pull/635)) * **Invest**: cap review loops at 2-3 rounds + hard 7-cycle breaker (owner directive) ([#623](https://github.com/smynkr/invest/pull/623)) * **Invest**: cap adversarial review loops ([#624](https://github.com/smynkr/invest/pull/624)) * **Invest**: TRD-966: gauntlet fixes + migration 0074 view guards + agent-worktree reclaim tooling ([#614](https://github.com/smynkr/invest/pull/614)) * **Invest**: TRD-948/940/941: exit-fill writeback reconciled with deployed master, position\_effect (0072), combo slippage normalization ([#608](https://github.com/smynkr/invest/pull/608)) * **Invest**: TRD-924/925: bounded short-PUT planned-risk fallback + env-controlled breakdown veto ([#606](https://github.com/smynkr/invest/pull/606)) * **Invest**: TRD-945/TRD-947: protection-latency sweep + governor clamp receipt ([#599](https://github.com/smynkr/invest/pull/599)) * **Invest**: TRD-939: wire rationale/confidence\_breakdown/sizing into the weekly decision-review evidence ([#604](https://github.com/smynkr/invest/pull/604)) * **Invest**: TRD-933/TRD-935: alerter crash-loop detection + self-observability ([#597](https://github.com/smynkr/invest/pull/597)) * **Invest**: TRD-929/TRD-935: budget-exhausted freshness status + alerter-timer watcher ([#598](https://github.com/smynkr/invest/pull/598)) * **Invest**: TRD-931/913/929/930: outage hardening — broker hard-exit watchdog, equity keep-warm, absolute decision-freshness alarm, drill procedure ([#596](https://github.com/smynkr/invest/pull/596)) * **Invest**: TRD-916/917/921: RTH conversion + bookkeeping repairs (mixed-combo generation filter, Track C warmer, close-tag effect override) ([#595](https://github.com/smynkr/invest/pull/595)) * **Invest**: align Invest public docs and memory config ([#593](https://github.com/smynkr/invest/pull/593)) * **Invest**: comprehensive read-only review + 3-family adversarial gauntlet (kimi-k3 / Codex Sol / Gemini 3.1 Pro) ([#571](https://github.com/smynkr/invest/pull/571)) ### Fixes [#fixes] * **Layer**: verify authoritative membership before issuing service-role client (LAY-768) ([#252](https://github.com/smynkr/axiomlayer/pull/252)) * **Layer**: isolate Git fixtures from hook state (LAY-766) ([#249](https://github.com/smynkr/axiomlayer/pull/249)) * **Layer**: enforce FOCUS 1.3 profile gate (LAY-747) ([#244](https://github.com/smynkr/axiomlayer/pull/244)) * **Layer**: upgrade Next.js to 16.2.12 to clear middleware/auth CVEs (LAY-739) ([#243](https://github.com/smynkr/axiomlayer/pull/243)) * **Layer**: pin Next.js to patched 16.2.12 (LAY-739) ([#241](https://github.com/smynkr/axiomlayer/pull/241)) * **Layer**: paginate reconciliation reads (LAY-748) ([#242](https://github.com/smynkr/axiomlayer/pull/242)) * **Layer**: enforce stable merge gates (LAY-725, LAY-746) ([#240](https://github.com/smynkr/axiomlayer/pull/240)) * **Layer**: reject malformed RouteShift usage (LAY-733) ([#237](https://github.com/smynkr/axiomlayer/pull/237)) * **Layer**: restore scheduled sync execution (LAY-737) ([#234](https://github.com/smynkr/axiomlayer/pull/234)) * **Layer**: preserve extension usage if gap storage fails (LAY-738) ([#233](https://github.com/smynkr/axiomlayer/pull/233)) * **Layer**: provision baseline subscriptions atomically (LAY-737) ([#231](https://github.com/smynkr/axiomlayer/pull/231)) * **Layer**: run docs-agent driver from the axiom-docs checkout (single source) ([#230](https://github.com/smynkr/axiomlayer/pull/230)) * **Layer**: per-request CSP nonce so Axiom Drift actually hydrates (LAY-761) ([#229](https://github.com/smynkr/axiomlayer/pull/229)) * **Layer**: restore FOCUS reconciliation source-derived expectations (LAY-735) ([#227](https://github.com/smynkr/axiomlayer/pull/227)) * **Layer**: disclose cost basis on the last three blind readers (LAY-734) ([#226](https://github.com/smynkr/axiomlayer/pull/226)) * **Layer**: remove reconciliation rules that could never fire (LAY-734) ([#224](https://github.com/smynkr/axiomlayer/pull/224)) * **Layer**: make all four FOCUS cost columns non-nullable and gate un-costed rows (LAY-734) ([#223](https://github.com/smynkr/axiomlayer/pull/223)) * **Layer**: stop the cost-basis caveat asserting what it cannot know (LAY-734) ([#222](https://github.com/smynkr/axiomlayer/pull/222)) * **Layer**: flag unrepairable rows when upstream returns no records (LAY-728) ([#219](https://github.com/smynkr/axiomlayer/pull/219)) * **Layer**: bill plugin surcharge into per-person RouteShift spend (LAY-728) ([#217](https://github.com/smynkr/axiomlayer/pull/217)) * **Overwatch**: harden sanctions identity query ([#361](https://github.com/smynkr/axiom-overwatch/pull/361)) * **Overwatch**: restore durable delivery and inbox state (AXO-479) ([#360](https://github.com/smynkr/axiom-overwatch/pull/360)) * **Overwatch**: support ANTAQ annual data bundles ([#351](https://github.com/smynkr/axiom-overwatch/pull/351)) * **Overwatch**: repair verification scratch-table RLS ([#349](https://github.com/smynkr/axiom-overwatch/pull/349)) * **Overwatch**: fail closed when a GLEIF load parses zero relationship rows ([#383](https://github.com/smynkr/axiom-overwatch/pull/383)) * **Overwatch**: raise CBP ingest attempts to 9/form and un-gate the primaries ([#382](https://github.com/smynkr/axiom-overwatch/pull/382)) * **Overwatch**: fail closed and fence UCC processing ([#355](https://github.com/smynkr/axiom-overwatch/pull/355)) * **Overwatch**: make deploy verification auth-aware ([#348](https://github.com/smynkr/axiom-overwatch/pull/348)) * **Overwatch**: fail closed on ambiguous UCC termination status ([#334](https://github.com/smynkr/axiom-overwatch/pull/334)) * **Overwatch**: escalate lifecycle-status date lines in UCC cheap path (AXO-465 fail-open) ([#375](https://github.com/smynkr/axiom-overwatch/pull/375)) * **Overwatch**: harden AXO-222 database readiness ([#378](https://github.com/smynkr/axiom-overwatch/pull/378)) * **Overwatch**: add -- end-of-options separator before server-controlled Location (AXO-634) ([#376](https://github.com/smynkr/axiom-overwatch/pull/376)) * **Overwatch**: make the CBP loader actually parse the live reports ([#374](https://github.com/smynkr/axiom-overwatch/pull/374)) * **Overwatch**: enforce bounded cargo validation matching ([#350](https://github.com/smynkr/axiom-overwatch/pull/350)) * **Overwatch**: contain AXO-436 adjudication queue server-side ([#354](https://github.com/smynkr/axiom-overwatch/pull/354)) * **Overwatch**: retry positions schema-cache reads (AXO-714) ([#359](https://github.com/smynkr/axiom-overwatch/pull/359)) * **Overwatch**: close AXO-423 detector evidence boundary ([#356](https://github.com/smynkr/axiom-overwatch/pull/356)) * **Overwatch**: degrade positions/latest gracefully when service-role key is absent (AXO-711) ([#343](https://github.com/smynkr/axiom-overwatch/pull/343)) * **Overwatch**: classify nonfatal resource errors (AXO-652, AXO-690) ([#367](https://github.com/smynkr/axiom-overwatch/pull/367)) * **Overwatch**: fail closed on ingestion run identity ([#368](https://github.com/smynkr/axiom-overwatch/pull/368)) * **Overwatch**: filter unattributable Server Action Sentry noise (AXO-448) ([#365](https://github.com/smynkr/axiom-overwatch/pull/365)) * **Overwatch**: reconcile AXO-418 schema drift and durable recovery ([#352](https://github.com/smynkr/axiom-overwatch/pull/352)) * **Overwatch**: gate route replay by port scope (AXO-688) ([#362](https://github.com/smynkr/axiom-overwatch/pull/362)) * **Overwatch**: close AXO-419 API and live-map gaps ([#353](https://github.com/smynkr/axiom-overwatch/pull/353)) * **Overwatch**: fall back from failed Mux hero playback (AXO-698, AXO-700) ([#366](https://github.com/smynkr/axiom-overwatch/pull/366)) * **Overwatch**: bound dashboard navigation prefetch fan-out (AXO-608) ([#364](https://github.com/smynkr/axiom-overwatch/pull/364)) * **Overwatch**: repair kinematic conformal test collection (AXO-422) ([#363](https://github.com/smynkr/axiom-overwatch/pull/363)) * **Overwatch**: drop unattributable browser-global onerror noise from Sentry (AXO-706) ([#344](https://github.com/smynkr/axiom-overwatch/pull/344)) * **Overwatch**: harden CBP loader failure handling + UTC occurred\_at ([#357](https://github.com/smynkr/axiom-overwatch/pull/357)) * **Overwatch**: pin Stripe apiVersion in stripe client ([#358](https://github.com/smynkr/axiom-overwatch/pull/358)) * **Overwatch**: retry transient AXO-222 image pulls ([#345](https://github.com/smynkr/axiom-overwatch/pull/345)) * **Overwatch**: restore AXO-417 Deno load contracts ([#342](https://github.com/smynkr/axiom-overwatch/pull/342)) * **Overwatch**: stabilize homepage hydration period (AXO-605) ([#336](https://github.com/smynkr/axiom-overwatch/pull/336)) * **Overwatch**: retry transient status-check schema cache writes (AXO-704) ([#335](https://github.com/smynkr/axiom-overwatch/pull/335)) * **Overwatch**: run docs-agent driver from the axiom-docs checkout (single source) ([#332](https://github.com/smynkr/axiom-overwatch/pull/332)) * **Overwatch**: harden confirmed production migration tranche ([#330](https://github.com/smynkr/axiom-overwatch/pull/330)) * **Overwatch**: stop status\_check silent-ingestion recursion ([#328](https://github.com/smynkr/axiom-overwatch/pull/328)) * **Overwatch**: redirect map-host dashboard deep links ([#326](https://github.com/smynkr/axiom-overwatch/pull/326)) * **Overwatch**: publish empty archives for all PMTiles sources ([#327](https://github.com/smynkr/axiom-overwatch/pull/327)) * **Overwatch**: publish valid empty tanker and bulker archives ([#322](https://github.com/smynkr/axiom-overwatch/pull/322)) * **Overwatch**: fail health closed on stale AISStream ([#323](https://github.com/smynkr/axiom-overwatch/pull/323)) * **Overwatch**: keep active AIS run open for streaming batches ([#321](https://github.com/smynkr/axiom-overwatch/pull/321)) * **Overwatch**: parse block-scalar skill descriptions ([#311](https://github.com/smynkr/axiom-overwatch/pull/311)) * **Overwatch**: lock cargo shim trim metadata parity ([#309](https://github.com/smynkr/axiom-overwatch/pull/309)) * **Overwatch**: harden pg-cron failure lookbacks (AXO-477) ([#307](https://github.com/smynkr/axiom-overwatch/pull/307)) * **Overwatch**: make obfuscation scoring writes honest ([#306](https://github.com/smynkr/axiom-overwatch/pull/306)) * **Overwatch**: harden Overwatch Live release and acceptance gates ([#305](https://github.com/smynkr/axiom-overwatch/pull/305)) * **Locus**: complete v2 temporal cutover ([#393](https://github.com/smynkr/axiom-locus/pull/393)) * **Locus**: restore AXC-373 scheduler acceptance ([#392](https://github.com/smynkr/axiom-locus/pull/392)) * **Locus**: deterministic archive batch selection — id tiebreaker (POI selector + archiveToR2) ([#386](https://github.com/smynkr/axiom-locus/pull/386)) * **Locus**: archive punch-list — missing-ETag fail-loud, run-completion null-guard, rowsArchived doc ([#385](https://github.com/smynkr/axiom-locus/pull/385)) * **Locus**: persist canonical R5 accessibility input ([#323](https://github.com/smynkr/axiom-locus/pull/323)) * **Locus**: add full unique index on archive\_log(table\_name,run\_id,batch\_num) — fixes receipt ON CONFLICT regression ([#381](https://github.com/smynkr/axiom-locus/pull/381)) * **Locus**: loss-safe R2 archive delete retries — FK-safe AIS delete + bounded POI delete ([#371](https://github.com/smynkr/axiom-locus/pull/371)) * **Locus**: AXL-506 parse composite keyset-cursor watermark prefix ([#375](https://github.com/smynkr/axiom-locus/pull/375)) * **Locus**: AXL-507 make civic\_records projection drop observable ([#374](https://github.com/smynkr/axiom-locus/pull/374)) * **Locus**: AXL-511 ledger-safe reconciliation of poisoned v1 cursor ([#373](https://github.com/smynkr/axiom-locus/pull/373)) * **Locus**: AXL-472 count state-total rows in patent join coverage ([#372](https://github.com/smynkr/axiom-locus/pull/372)) * **Locus**: AXL-472 persist skipped\_non\_grant\_count for non-grant PTGRXML docs ([#367](https://github.com/smynkr/axiom-locus/pull/367)) * **Locus**: align freshness source count with evidence ([#364](https://github.com/smynkr/axiom-locus/pull/364)) * **Locus**: accept duplicate historical migration names ([#363](https://github.com/smynkr/axiom-locus/pull/363)) * **Locus**: apply post-review EPA permit hardening ([#360](https://github.com/smynkr/axiom-locus/pull/360)) * **Locus**: AXL-510 FtM Airplane schema + AXL-294 revoke heavy RPC public execute ([#359](https://github.com/smynkr/axiom-locus/pull/359)) * **Locus**: OpenSanctions bulk APRS envelope + FTM provisions parity ([#337](https://github.com/smynkr/axiom-locus/pull/337)) * **Locus**: quiesce HMDA cron through scheduler API ([#358](https://github.com/smynkr/axiom-locus/pull/358)) * **Locus**: repair managed pg\_cron terminal path ([#357](https://github.com/smynkr/axiom-locus/pull/357)) * **Locus**: stamp HMDA APRS envelope at write time ([#349](https://github.com/smynkr/axiom-locus/pull/349)) * **Locus**: backfill unknown ruling occurrence timestamps (AXL-503) ([#350](https://github.com/smynkr/axiom-locus/pull/350)) * **Locus**: harden Stripe webhook onConflict + ordering safety ([#356](https://github.com/smynkr/axiom-locus/pull/356)) * **Locus**: pin Stripe apiVersion in stripe client ([#354](https://github.com/smynkr/axiom-locus/pull/354)) * **Locus**: reconcile live migration version ([#352](https://github.com/smynkr/axiom-locus/pull/352)) * **Locus**: APRS coverage audit fabricated schema-missing findings from sample-query errors ([#347](https://github.com/smynkr/axiom-locus/pull/347)) * **Locus**: registration exemptions for 9 secondary destinations (AXC-252 audit findings) ([#345](https://github.com/smynkr/axiom-locus/pull/345)) * **Locus**: run\_all aggregate uses partial\_result attribute (contract consistency) ([#340](https://github.com/smynkr/axiom-locus/pull/340)) * **Locus**: require accepted Scout catalog watermarks ([#326](https://github.com/smynkr/axiom-locus/pull/326)) * **Locus**: enforce canonical civic record writes ([#327](https://github.com/smynkr/axiom-locus/pull/327)) * **Locus**: fail loudly on incomplete government dataset loads ([#336](https://github.com/smynkr/axiom-locus/pull/336)) * **Locus**: atomically bind FAF5 completion evidence ([#324](https://github.com/smynkr/axiom-locus/pull/324)) * **Locus**: enforce strict OpenSanctions scheduler results ([#331](https://github.com/smynkr/axiom-locus/pull/331)) * **Locus**: add 'provisions' to TS Sanction allowlist + interface (Python↔TS parity) ([#338](https://github.com/smynkr/axiom-locus/pull/338)) * **Locus**: bound OSHA archive downloads ([#335](https://github.com/smynkr/axiom-locus/pull/335)) * **Locus**: route DOI PAL to operator-auth hold ([#320](https://github.com/smynkr/axiom-locus/pull/320)) * **Locus**: prevent demographics RPC integer overflow ([#318](https://github.com/smynkr/axiom-locus/pull/318)) * **Locus**: run docs-agent driver from the axiom-docs checkout (single source) ([#313](https://github.com/smynkr/axiom-locus/pull/313)) * **RouteShift**: pin Stripe apiVersion in savings-reporter ([#186](https://github.com/smynkr/RouteShift/pull/186)) * **RouteShift**: clear stale DEK version on provider-key rotation ([#180](https://github.com/smynkr/RouteShift/pull/180)) * **RouteShift**: harden provider-key envelope reads ([#179](https://github.com/smynkr/RouteShift/pull/179)) * **RouteShift**: observe gated credential load and cooldowns ([#178](https://github.com/smynkr/RouteShift/pull/178)) * **RouteShift**: reconcile unknown provider costs safely (RSH-149) ([#177](https://github.com/smynkr/RouteShift/pull/177)) * **RouteShift**: restore CI and harden shadow experiment controls ([#176](https://github.com/smynkr/RouteShift/pull/176)) * **RouteShift**: run docs-agent driver from the axiom-docs checkout (single source) ([#175](https://github.com/smynkr/RouteShift/pull/175)) * **RouteShift**: downgrade CSP report logging from warn to info ([#169](https://github.com/smynkr/RouteShift/pull/169)) * **RouteShift**: de-stale /compare/openrouter against OpenRouter's shipped features (RSH-144) ([#167](https://github.com/smynkr/RouteShift/pull/167)) * **Codex**: run docs-agent driver from the axiom-docs checkout (single source) ([#116](https://github.com/smynkr/axiomcodex/pull/116)) * **Codex**: harden portal ontology and family contracts (AXC-286/289/290) ([#94](https://github.com/smynkr/axiomcodex/pull/94)) * **Codex**: harden audited boundaries (AXC-292 AXC-293 AXC-294) ([#93](https://github.com/smynkr/axiomcodex/pull/93)) * **Codex**: harden AIS, identity, and entitlement gates (AXC-287/321/333) ([#92](https://github.com/smynkr/axiomcodex/pull/92)) * **Codex**: harden lineage and release audit integrity (AXC-320, AXC-330, AXC-352) ([#91](https://github.com/smynkr/axiomcodex/pull/91)) * **Codex**: harden permit, KG, and ingestion boundaries ([#90](https://github.com/smynkr/axiomcodex/pull/90)) * **Codex**: close identity and release-operation gaps (AXC-321/333/354) ([#89](https://github.com/smynkr/axiomcodex/pull/89)) * **Codex**: close fail-open identity gaps (AXC-343/346/351) ([#88](https://github.com/smynkr/axiomcodex/pull/88)) * **Codex**: fail closed on temporal, permit, and OSHA evidence ([#87](https://github.com/smynkr/axiomcodex/pull/87)) * **Invest**: align cache admission probe authority ([#701](https://github.com/smynkr/invest/pull/701)) * **Invest**: isolate Nautilus cache authority ([#699](https://github.com/smynkr/invest/pull/699)) * **Invest**: \_persist\_event returns True on committed write — volume-control dedup now engages ([#687](https://github.com/smynkr/invest/pull/687)) * **Invest**: EOD brief fires on weekends/holidays and reads a UTC "today" ([#661](https://github.com/smynkr/invest/pull/661)) * **Invest**: never let a price stop sell a load-bearing protective long ([#684](https://github.com/smynkr/invest/pull/684)) * **Invest**: TRD-1054 — entry fence must never publish a transient OPEN verdict ([#678](https://github.com/smynkr/invest/pull/678)) * **Invest**: TRD-1025 lane-A/B per-class critical cooldown ([#659](https://github.com/smynkr/invest/pull/659)) * **Invest**: TRD-1045 — stop the reconciler queueing starts behind an in-flight stop, + page on in-session restart storms ([#672](https://github.com/smynkr/invest/pull/672)) * **Invest**: nautilus int-backed enums silently disabled three side checks (close-tag override, naked-short shadow cover, lifecycle leg matcher) ([#660](https://github.com/smynkr/invest/pull/660)) * **Invest**: TRD-1033 — concurrent deploy-writer refusal fails CLOSED (exit 1 + audited break-glass) ([#670](https://github.com/smynkr/invest/pull/670)) * **Invest**: TRD-1042 null ibapi UNSET sentinels at the audit-write seam + TRD-1015 exclude-and-log impossible price evidence in small-n drift ([#665](https://github.com/smynkr/invest/pull/665)) * **Invest**: TRD-1046 — persist entry-blocking equity-baseline state to runtime\_events ([#674](https://github.com/smynkr/invest/pull/674)) * **Invest**: TRD-1017 (PARTIAL — does NOT close the ticket) — decouple the account-scoped open witness from position-truth ([#664](https://github.com/smynkr/invest/pull/664)) * **Invest**: TRD-1018 journal pointer in the probe Repair line + TRD-1020 page on drain probe error ([#666](https://github.com/smynkr/invest/pull/666)) * **Invest**: TRD-1025 — differentiate lane-A/B critical page content ([#655](https://github.com/smynkr/invest/pull/655)) * **Invest**: TRD-928 follow-up — detect-and-report combo-LEG classification (not silent-waive) ([#658](https://github.com/smynkr/invest/pull/658)) * **Invest**: TRD-928 combo-LEG parent-aware orphan classification ([#654](https://github.com/smynkr/invest/pull/654)) * **Invest**: TRD-949 — durable event-time edge/tier evidence for clamp decisions ([#648](https://github.com/smynkr/invest/pull/648)) * **Invest**: TRD-950 — close-ledger fail-open capture for cache-absent positions ([#646](https://github.com/smynkr/invest/pull/646)) * **Invest**: TRD-1011 h2h residuals, rebased + re-adjudicated vs master (Part of TRD-1011/TRD-1012) ([#642](https://github.com/smynkr/invest/pull/642)) * **Invest**: TRD-989/996/997 — EOD brief fills-day caveat + close-book completeness ([#631](https://github.com/smynkr/invest/pull/631)) * **Invest**: TRD-985 gauntlet-lint P0/hypothesis-leak gaps; TRD-992 mypy comment refresh ([#626](https://github.com/smynkr/invest/pull/626)) * **Invest**: TRD-1010 — scheduled brief failures are now loud, not invisible ([#634](https://github.com/smynkr/invest/pull/634)) * **Invest**: TRD-999/1000 — wiki\_code\_drift fails closed on git errors, adds PR-stage range check ([#627](https://github.com/smynkr/invest/pull/627)) * **Invest**: TRD-1012 — name every dropped tagged dispatch event; provenance has\_decision\_id + ERROR writeback ([#640](https://github.com/smynkr/invest/pull/640)) * **Invest**: TRD-983 — wait\_for\_green do-while probing, monotonic $SECONDS deadline, terminal log ([#628](https://github.com/smynkr/invest/pull/628)) * **Invest**: TRD-994 — deterministic panic-flatten native alert dialog handling ([#630](https://github.com/smynkr/invest/pull/630)) * **Invest**: TRD-969/971/990 — alerter-timer proof, lane-drift guard, ET day windows ([#636](https://github.com/smynkr/invest/pull/636)) * **Invest**: TRD-1001 — dual-condition slippage outlier clamp for low-priced options ([#629](https://github.com/smynkr/invest/pull/629)) * **Invest**: TRD-1014 — gauntlet\_lane\_call.sh makes inline-key argv exposure mechanically impossible ([#638](https://github.com/smynkr/invest/pull/638)) * **Invest**: TRD-970 — trade\_quality\_target absent-knob debug parity line ([#633](https://github.com/smynkr/invest/pull/633)) * **Invest**: TRD-1011 — record lot provenance for generic-spread leg fills ([#632](https://github.com/smynkr/invest/pull/632)) * **Invest**: TRD-954/955/956 lifecycle-provider connect bounds, durability-degraded severity, restart-guard age bounds ([#619](https://github.com/smynkr/invest/pull/619)) * **Invest**: armed-halt visibility, halt-class split, pre-arm unseeded-baseline guard ([#617](https://github.com/smynkr/invest/pull/617)) * **Invest**: TRD-846 lot-attribution legacy fallthrough + decision-id backfill ([#625](https://github.com/smynkr/invest/pull/625)) * **Invest**: tag-derived close-row convention, duplicate-row self-heal, pin/expiry CAS heal, orders\_schema logging ([#621](https://github.com/smynkr/invest/pull/621)) * **Invest**: checkout-failure ordering, governor out-of-window review, guard-error isolation ([#618](https://github.com/smynkr/invest/pull/618)) * **Invest**: EOD brief error-visibility + transaction hygiene ([#615](https://github.com/smynkr/invest/pull/615)) * **Invest**: withhold NULL-limit combo rows, add outlier clamp + order\_origin exclusion ([#616](https://github.com/smynkr/invest/pull/616)) * **Invest**: TRD-840 escalation tool-call budget default 12→20 + regression guard ([#622](https://github.com/smynkr/invest/pull/622)) * **Invest**: TRD-973 — un-vacuous wiki-code-drift gate (fetch-depth: 0) ([#613](https://github.com/smynkr/invest/pull/613)) * **Invest**: deploy-gate harness GREEN/ROLLBACK budgets 1s -> 3s (CI false-RED race) ([#611](https://github.com/smynkr/invest/pull/611)) * **Invest**: decision\_scorer decision\_count counts synthetic admission rows (TRD-961) ([#605](https://github.com/smynkr/invest/pull/605)) * **Invest**: persist lifecycle-close orders to invest\_state.orders ([#602](https://github.com/smynkr/invest/pull/602)) * **Invest**: force IdentityAgent=none on all workstation→box ssh (1P agent hang, TRD-951) ([#603](https://github.com/smynkr/invest/pull/603)) * **Invest**: exhaustion-boot deadlock — admission no\_action row + generator chain-snapshot Redis reseed ([#600](https://github.com/smynkr/invest/pull/600)) * **Invest**: multi-expiration detector chain coverage — otm\_calls/otm\_puts structural starvation ([#590](https://github.com/smynkr/invest/pull/590)) * **Invest**: force-release wedged decision cycles + bounded conservative spend terminalization ([#591](https://github.com/smynkr/invest/pull/591)) * **Invest**: remove lifecycle\_exit.ruin\_fence\_blocked from DEPLOY\_TOLERATED\_CRITICAL\_EVENTS ([#589](https://github.com/smynkr/invest/pull/589)) * **Invest**: correlate proposals to orders by decision\_id — counts cannot mask a dropped proposal ([#588](https://github.com/smynkr/invest/pull/588)) * **Invest**: rc-check and prove the TARGET trader restart before wait\_for\_green ([#587](https://github.com/smynkr/invest/pull/587)) * **Invest**: close-evidence instrument-identity bridge — stop a different contract's close from suppressing the gap alert ([#586](https://github.com/smynkr/invest/pull/586)) * **Invest**: dedupe deployment-governor would-clamp knob\_audit spam ([#585](https://github.com/smynkr/invest/pull/585)) * **Invest**: make propose\_to\_submit\_parity readiness probe gate-aware ([#584](https://github.com/smynkr/invest/pull/584)) * **Invest**: dispatch durable-spend Lua test fakes by exact marker, not substring ([#583](https://github.com/smynkr/invest/pull/583)) * **Invest**: emergency-close realized-trade synthesis + snapshot-to-ledger gap alert ([#561](https://github.com/smynkr/invest/pull/561)) * **Invest**: trading-health alerter pages severity=critical events regardless of log level ([#581](https://github.com/smynkr/invest/pull/581)) * **Invest**: deploy\_recon\_probe scans HASH-type order\_position index for class-C orphans ([#580](https://github.com/smynkr/invest/pull/580)) * **Invest**: claim mid-session instruments so reconciliation stops minting EXTERNAL sibling Positions ([#578](https://github.com/smynkr/invest/pull/578)) * **Invest**: unpriced LLM lane must not poison the spend-cap machinery ([#579](https://github.com/smynkr/invest/pull/579)) * **Invest**: triage post-green criticals by event class instead of counting (TRD-879) ([#575](https://github.com/smynkr/invest/pull/575)) * **Invest**: fail closed at boot if the INVEST\_ISOLATED\_CONTEXT hatch would be open ([#574](https://github.com/smynkr/invest/pull/574)) # Changelog (/changelog) What's new across the platform. Newer releases at the top. Release notes are dated records, not the current product contract. For Overwatch chokepoints, launch-supported confirmation is currently AIS-only; the Sentinel endpoint reports scene catalog coverage and does not detect vessels or confirm transits. See [Chokepoint transits](/overwatch/methodology/chokepoint-transits) and [Sentinel-1 catalog coverage](/overwatch/api/sar-coverage). {/* WEEKLY-RECAP:INSERT */} {/* WEEKLY-RECAP:2026-08-01:START */} ## Week of July 26 – August 1, 2026 — 319 user-facing PRs across Layer, Overwatch, Locus, RouteShift, Codex, and Invest [#week-of-july-26--august-1-2026--319-user-facing-prs-across-layer-overwatch-locus-routeshift-codex-and-invest] 319 user-facing PRs merged in this completed window. ### Highlights [#highlights] * **Layer**: add admin-client membership guard ratchet (LAY-749) ([#246](https://github.com/smynkr/axiomlayer/pull/246)) * **Overwatch**: advance Overwatch Live code-safe acceptance tranche ([#333](https://github.com/smynkr/axiom-overwatch/pull/333)) * **Locus**: AXL-519 OSHA PSM citations table (APRS + RLS) ([#391](https://github.com/smynkr/axiom-locus/pull/391)) * **RouteShift**: RSH-151 + RSH-152 admin config CRUD for classifier and guardrails ([#183](https://github.com/smynkr/RouteShift/pull/183)) * **Codex**: APRS->HF staging transform + reclassify 3 dead-endpoint feeds to manual\_only ([#124](https://github.com/smynkr/axiomcodex/pull/124)) * **Invest**: add native cache recovery and quarantine contracts ([#703](https://github.com/smynkr/invest/pull/703)) See the [full weekly recap](/changelog/2026-08-01-weekly) for every included change and its source PR. {/* WEEKLY-RECAP:2026-08-01:END */} {/* WEEKLY-RECAP:2026-07-25:START */} ## Week of July 19–25, 2026 — 115 user-facing PRs across Layer, Overwatch, Locus, RouteShift, Codex, and Invest [#week-of-july-1925-2026--115-user-facing-prs-across-layer-overwatch-locus-routeshift-codex-and-invest] 115 user-facing PRs merged in this completed window. ### Highlights [#highlights-1] * **Layer**: LiteLLM pricing, CI cost controls, landing viz (LAY-313/712/718) ([#211](https://github.com/smynkr/axiomlayer/pull/211)) * **Overwatch**: integrate and harden Launch 4.0 on current main ([#292](https://github.com/smynkr/axiom-overwatch/pull/292)) * **Locus**: make score explanations truthful and usable ([#299](https://github.com/smynkr/axiom-locus/pull/299)) * **RouteShift**: preserve native provider tool turns (RSH-68) ([#125](https://github.com/smynkr/RouteShift/pull/125)) * **Codex**: P2 remediation from 3-lane adversarial review (source types, family consistency, baseline scores) ([#101](https://github.com/smynkr/axiomcodex/pull/101)) * **Invest**: reasoning-trace observability — capture, persist, score extended thinking (TRD-863 WS5) ([#568](https://github.com/smynkr/invest/pull/568)) See the [full weekly recap](/changelog/2026-07-25-weekly) for every included change and its source PR. {/* WEEKLY-RECAP:2026-07-25:END */} ## Week of July 12–18, 2026 — Layer dashboard v2, Overwatch port commodity contracts and ENSO-aware forecast, Locus data contracts, Codex Graph tranche, RouteShift SSO hardening [#week-of-july-1218-2026--layer-dashboard-v2-overwatch-port-commodity-contracts-and-enso-aware-forecast-locus-data-contracts-codex-graph-tranche-routeshift-sso-hardening] A heavy ship week across all five products. Layer shipped the console dashboard v2 and a database hardening pass; Overwatch published port commodity contract v1, point-in-time weather and cargo residual contracts, and an ENSO/ONI-aware seasonal grain-export forecast; Locus landed a fail-closed parcel pilot contract, a land-face publish path, and replayable aggregate score evidence; Codex delivered its reviewed Graph governance tranche; and RouteShift closed a five-hole security review on the SSO device flow. ### Highlights [#highlights-2] * **Layer**: Console dashboard v2 — KPI cards backed by real data, trend sparklines, period-aware benchmark annualization, and action insights * **Overwatch**: Port commodity contract v1, weather and cargo residual contracts, and an ENSO/ONI-aware seasonal grain-export forecast * **Locus**: Fail-closed parcel pilot contract, land-face publish path, and replayable aggregate score evidence * **Codex**: Graph governance and packaging tranche with hardened evaluation splits and signoff evidence * **RouteShift**: SSO device-flow security review — HTTPS-only discovery, per-IP DoS ceiling, fail-closed `email_verified` See the [full weekly recap](/changelog/2026-07-19-weekly) for every included change and its source PR. ## Week of July 5–11, 2026 — RouteShift native SSO device-flow CLI login, live web-search augmentation plugin, money-path hardening, reasoning-effort and thinking-budget become routing-rule fields, percentage-mode circuit breaker, model-drift detection cron, Codex research-tier datasets on Hugging Face [#week-of-july-511-2026--routeshift-native-sso-device-flow-cli-login-live-web-search-augmentation-plugin-money-path-hardening-reasoning-effort-and-thinking-budget-become-routing-rule-fields-percentage-mode-circuit-breaker-model-drift-detection-cron-codex-research-tier-datasets-on-hugging-face] ### New features [#new-features] * **RouteShift**: Native **SSO device-flow login** for the [`connect` CLI](/routeshift/getting-started). Employees at a Google Workspace or Okta org run the CLI, get an 8-character code, approve it in their browser through the org's real IdP, and receive a short-lived (8-hour) self-service [virtual key](/routeshift/keys) — no admin has to mint or share credentials. Every issuance is written to the workspace [audit log](/routeshift/team). See the [weekly recap](/changelog/2026-07-11-weekly). * **RouteShift**: New **[web search plugin](/routeshift/web-search)** for any chat completion. Opt in per request with a `:online` model suffix or an explicit `plugins` entry, and RouteShift injects fresh, cited web results into the system prompt before it dispatches upstream. Augmented turns are non-cacheable, and `required: true` callers get a clean `plugin_required_failed` on backend failure instead of a silently un-augmented response. See the [July 10 daily entry](/changelog/2026-07-10). * **Codex**: Six new [research-tier](/codex/data-catalog) datasets on the [Axiom AI Hugging Face organization](https://huggingface.co/axiom-ai) — [AIS Maritime](/codex/schemas/ais-maritime), [Events Timeline](/codex/schemas/events-timeline), [OSHA Safety](/codex/schemas/osha-safety), [LEHD Commuter Flows](/codex/schemas/lehd-commuter-flows), [POI Intelligence](/codex/schemas/poi-intelligence), and [Permit Signals](/codex/schemas/permit-signals). Each is a deterministic 100K-record stratified sample in Parquet under CC-BY-4.0, shipped with a README, schema, and the standard [APRS envelope](/codex/normalization-standard). * **RouteShift**: `reasoning_effort` and `thinking_budget_tokens` are now modifiable [routing-rule fields](/routeshift/routing) — rules can dial reasoning effort or extended-thinking budget per match, and both fields also participate in the response cache key so `high`-effort and `low`-effort calls to the same prompt no longer collide on a cache hit. * **RouteShift**: The [circuit breaker on load-balanced provider keys](/routeshift/routing) gained an optional **percentage-based trip mode** — a credential can be parked when its error rate crosses a threshold within a sliding window instead of on a raw count of `5xx`/`429`. * **RouteShift**: New **model-drift detection** cron runs weekly and proposes newly-released models as *parked* [catalog entries](/routeshift/savings-and-pricing) — never auto-routed — so a human reviews and approves a new model before any traffic lands on it. * **RouteShift**: Weekly [pricing sync](/routeshift/savings-and-pricing) coverage extended to more providers. * **RouteShift**: [Preset](/routeshift/routing) **version history** is now visible in the dashboard — list past versions of any named preset (newest first) and open a single revision with its model, params, system prompt, provider preferences, author, and timestamp. See the [July 10 daily entry](/changelog/2026-07-10). ### Updates [#updates] * **RouteShift**: [Credit reservation](/routeshift/billing) now happens *before* dispatch on every credits-mode path — concurrent large requests from the same key can no longer both pass a stale balance check and dispatch. See the [weekly recap](/changelog/2026-07-11-weekly). * **RouteShift**: [Response cache](/routeshift/observability) now invalidates on provider-key rotation, so a rotated-out credential can't resurface content on a cache hit. * **RouteShift**: [Billing-mode](/routeshift/billing) changes invalidate the cached mode read at the same time — a switch between credits mode and the 3% savings-share takes effect on the next request. * **RouteShift**: Dispute reinstatement is symmetric — a Stripe chargeback that resolves in your favor restores credits to the same ledger balance the debit came from. * **RouteShift**: Operator-funded [prompt-optimizer](/routeshift/optimize) spend cap per workspace, plus a Sentry alert on missing-pricing gaps outside credits mode. ### Fixes [#fixes] * **RouteShift**: Streaming settle-failure no longer refunds already-delivered content — settlement now distinguishes delivery from settlement so a partial failure only refunds what wasn't received. * **RouteShift**: [Auto-topup](/routeshift/billing) webhook backfill for a worker-crash window — restarts reconcile Stripe against ledger state and stamp the cooldown timestamp so no window is retried twice. * **RouteShift**: [Response-cache](/routeshift/observability) writes now use the configured TTL end-to-end instead of collapsing to a 1-hour TTL on long-lived entries. * **RouteShift**: `custom`-condition [routing rules](/routeshift/routing) fail closed — a malformed predicate is rejected at save time and never matches at runtime, instead of matching every request. * **RouteShift**: A `keyHasReadScope` gate closes a scope-bypass on [usage and generation-lookup](/routeshift/observability) endpoints; a read-scoped [virtual key](/routeshift/keys) can no longer reach admin-usage endpoints intended for full-scope keys. * **RouteShift**: Team-invitation accept race fixed — accepting a [team](/routeshift/team) invitation twice can no longer produce a duplicate membership row. * **RouteShift**: `connect --tool claude-code` no longer overwrites an existing tool config file when re-run against the same tool; the [connect CLI](/routeshift/getting-started) merges or prompts instead. * **RouteShift**: [Preset](/routeshift/presets) write responses now report an explicit `proxy_cache_invalidated` outcome (and `proxy_cache_invalidation_failed` with a TTL on failure), so callers see when a committed preset change hasn't yet propagated to the proxy cache instead of a silent success. See the [July 10 daily entry](/changelog/2026-07-10). * **Codex**: The Chicago [building-inspection records](/codex/normalization-standard) dataset now carries the correct `source_uri` on every one of 4,299 rows, and the daily cron that keeps it current has been restored. See the [July 9 daily entry](/changelog/2026-07-09). * **Locus**: The **USDA SNAP retailers** roster behind the [`amenityDemand`](/locus/scoring-conventions) food-access sub-signal has been deduplicated (544,419 excess rows removed) and switched from a monthly truncate-and-reload to a resumable incremental upsert, so food-access scoring is now driven by an accurate retailer count and stays current between USDA publications. See the [July 9 daily entry](/changelog/2026-07-09). * **Layer**: **Google sign-in restored** — Google Workspace users signing in through [Auth0 Universal Login](/layer/getting-started) reach the Layer app cleanly again after an internal token-verification mismatch had been rejecting valid magic-link callbacks. See the [July 10 daily entry](/changelog/2026-07-10). * **Locus**: The nightly [HMDA multifamily](/locus/scoring-conventions) collector no longer trusts a CFPB server-side filter that silently stopped working on 2026-07-01 — the loader now filters multifamily records client-side, enforces a per-state ceiling that fails loudly instead of over-ingesting, and correctly stamps `property_type` on ingested rows for the first time. See the [July 10 daily entry](/changelog/2026-07-10). ## Week of May 17–23, 2026 — Locus recent-hazards panel, Overwatch live-map and archive reliability. Locus score-components bar and live time-series chart, Overwatch Marshall Islands IRI enrichment restored [#week-of-may-1723-2026--locus-recent-hazards-panel-overwatch-live-map-and-archive-reliability-locus-score-components-bar-and-live-time-series-chart-overwatch-marshall-islands-iri-enrichment-restored] ### New features [#new-features-1] * **Locus**: New **Recent hazards** section on every [cell detail](/locus/api/enrichment) page — NASA FIRMS active fires from the trailing 180 days (with fire radiative power per detection) and USGS earthquakes from the trailing 5 years (with max magnitude and per-event magnitude/type), joined on H3 equality so the panel answers "what happened *here*" rather than "what happened nearby." See the [weekly recap](/changelog/2026-05-23-weekly). * **Locus**: Real **score components** bar chart now sits beside the radar octagon on the cell [score breakdown](/locus/scoring-conventions) — all eight canonical signal groups render as sortable bars with sub-score, weight, and confidence chips. See the [weekly recap](/changelog/2026-05-23-weekly). * **Locus**: The score-history chart in the [Explorer](/locus/explorer) left sidebar is now a real interactive visx time series pulling composite and per-group trends from `/api/score-trends`, with toggleable 30-, 60-, and 90-day windows. ### Fixes [#fixes-1] * **Overwatch**: The public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint that powers the live map and the marketing hero map no longer times out under load — a dead-weight exact-count query that had been tripping the database's 10-second statement timeout and surfacing as 500s has been removed. Response shape is unchanged. * **Overwatch**: The nightly [dark events](/overwatch/api/risk) archive cron is current again. The range scan that walks events older than the retention cutoff now uses a dedicated index, so the job completes as a cheap index walk instead of a sequential scan plus sort. * **Locus**: Automated [FOIA portal submission](/locus/business-licenses) for foia.gov now follows the portal's current React-based workflow (agency search, agency detail, per-component request form) instead of the retired `/request/` URL. Captcha-protected agencies are reported with a clear `captcha_detected` marker in monitoring. * **Locus**: Granicus-hosted [council meetings](/codex/schemas/civic-intelligence) now consistently carry the correct metro tag at ingest, matching the parity already in place for Legistar cities. * **Overwatch**: Marshall Islands IRI [vessel-registry enrichment](/overwatch/api/vessels) is producing typed records again — the scraper now handles the upstream portal's new ADF form layout alongside the legacy fields, and a deterministic parser writes IMO, official number, and vessel name directly into the enrichment record. ## Week of May 10–16, 2026 — Overwatch ghost-vessel inference, Layer Slack OAuth, Locus discover filters [#week-of-may-1016-2026--overwatch-ghost-vessel-inference-layer-slack-oauth-locus-discover-filters] ### New features [#new-features-2] * **Overwatch**: New **Ghost Vessels** layer on the [alerts dashboard](/changelog/2026-05-16-weekly). Reverse-COLREGS solver back-solves the implied counterpart's position, course, and speed for each candidate encounter type when a solo vessel makes an unprovoked starboard alter with no other vessel inside 6 NM. Surfaces on the live map as a confidence-shaded "?"-labeled circle alongside a **Ghost Inferences** panel and a public `GET /api/v1/ghost-inferences` endpoint. * **Overwatch**: Course-alteration anomalies now appear in the **unified alerts inbox** alongside dark events, spoofing alerts, and Locus signals, with severity bucketed by turn magnitude. A matching **Course alteration** template lands in the [Alert Rule Builder](/overwatch/api/alerts). * **Layer**: One-click admin-consent OAuth ships for [Slack](/layer/integrations/slack), [Notion](/layer/integrations/notion), and Atlassian. Slack moves from a workspace-subdomain + bot-token paste form to a "Sign in with Slack" button. Existing manual-paste connections keep working. * **Locus**: New **Pioneer Signal** and **Permit Velocity** filters on [`/discover`](/locus/getting-started). Filter cells by pioneer-signal status (none, emerging, active, advanced) and by per-metro permit-velocity percentile over the trailing 12 months. * **Locus**: New **score direction** and **delta window** filters on [`/discover`](/locus/getting-started) — rising/falling cells over a 7-, 30-, or 90-day window, with a signed-Δ badge per row and CSV export columns to match. * **Codex**: New **civic intelligence LLM extractor** populates extracted entities, blockers, contingency dependencies, litigation-risk score, and a hostility index on council and zoning decisions in the [civic intelligence dataset](/codex/schemas/civic-intelligence). * **Codex**: Publish-ready `axiom_events` view filters internal-only sources out of the public events stream. ### Updates [#updates-1] * **Overwatch**: COLREGS [compliance scoring](/overwatch/methodology/encounter-extraction) is now port-context-aware — encounters are tagged `anchorage`, `approach`, or `open_sea` from CPA midpoint geometry and the safe-distance threshold scales accordingly (0.1 NM / 0.2 NM / 0.5 NM). Routine port traffic is no longer flagged as non-compliant. * **Overwatch**: [Pairwise encounter extraction](/overwatch/methodology/encounter-extraction) is more resilient on dense corridors — paginated 1,000-row batches and a 250,000-pair safety cap, with the default window widened to 90 minutes. * **Codex**: Council-meeting extraction across Granicus-hosted cities now uses a JavaScript-aware crawler; Seattle joins the roster. A new PDF extraction pipeline lifts text and structured layout out of scanned filings. ### Fixes [#fixes-2] * **Overwatch**: `axiom_events` envelope trigger no longer references a non-existent column on event tables without a metro slug. * **Overwatch**: Ingestion logs from the `fetch-imls` and `osm-cultural` Edge Functions always land a terminal row, even on mid-flight errors. * **Codex**: USPS vacancy ingestion surfaces a clean error when the upstream archive serves an HTML error page or a corrupt zip, instead of wedging the daily run. ## Week of May 3–9, 2026 — Layer asset management and 4 new connectors, Overwatch Rule 17 deviation flags, NOAA water density into cargo validation, production sweep, Layer and Drift CSP hardening [#week-of-may-39-2026--layer-asset-management-and-4-new-connectors-overwatch-rule-17-deviation-flags-noaa-water-density-into-cargo-validation-production-sweep-layer-and-drift-csp-hardening] ### New features [#new-features-3] * **Layer**: Asset management lands in the [Layer dashboard](/changelog/2026-05-09-weekly) — manual asset creation, CSV import up to 1,000 rows, and reusable **asset bundles** with a cost rollup and one-click assignment to a user. This is a dated release record; the [current bundle flow](/layer/asset-bundles) matches repeatable hardware kits against existing serialized inventory and does not create assets or provision SaaS licenses. * **Layer**: Three new SaaS-discovery connectors land on the [integrations catalog](/layer/integrations/overview) — **Microsoft Teams**, **[Atlassian](/layer/integrations/atlassian)** (Jira / Confluence / etc., per-product SaaS app with per-user last-active), and **Workday HRIS** (paginated workers with department, cost center, termination), the platform's first dedicated HRIS source. **Gmail Receipt Scanner** is also now available for Layer, surfacing SaaS receipts from Gmail and Microsoft 365 mail as assets via the standard sync route with a 12-month initial scan window. * **Layer**: The [GitHub](/layer/integrations/github) connector now emits a User per organization member with last-active timestamps and a separate **Copilot License** asset per active assignment, so Copilot seats appear directly in license inventory and access reviews. It also emits a Team asset per GitHub team with **MemberOf** (user → team) and **GovernedBy** (repository → team) relationships, so team membership and repo governance surface alongside the org. The [Google Workspace](/layer/integrations/google-workspace) and Microsoft Entra ID connectors also emit a SaaS app per third-party OAuth grant detected during sync, so apps connected with "Sign in with Google" or "Sign in with Microsoft" surface on the [integrations](/layer/integrations/overview) inventory automatically. The [Okta](/layer/integrations/okta) connector now also emits a SaaS app per Okta-managed application and a per-user assignment for every user→app pairing, so dormant accounts and oversized license footprints surface in [access reviews](/layer/access-reviews) without a manual cross-reference. The JumpCloud connector now emits a SaaS app per app surfaced in the trailing 30 days of SSO events, plus **Uses** relationships per user→app pair and **MemberOf** relationships for every user group, so JumpCloud-managed seats and group memberships roll into the inventory alongside Okta and OneLogin. * **Overwatch**: Rule 17 deviation flags on [vessel-to-vessel encounters](/changelog/2026-05-09-weekly). Each [pairwise encounter](/overwatch/methodology/encounter-extraction) now carries per-vessel `max_course_change_deg` and `rule17_deviation` fields. The flag fires when a vessel's mean stand-on probability across the encounter is at least 0.6 *and* its largest single-step course change is 10° or more — a stand-on vessel taking unilateral evasive action that COLREGS Rule 17 only authorizes when the give-way vessel has clearly failed to keep clear. Useful for surfacing unannounced maneuvers, attributing close-quarters action to the correct party, and cueing forensic review. * **Overwatch**: Per-port surface [water density](/overwatch/methodology/cargo-validation#water-density-sources) now refreshes monthly into the [cargo validation](/overwatch/methodology/cargo-validation) pipeline. NOAA CO-OPS real-time temperature for major US ports (New Orleans, Houston, Baltimore, Norfolk, Los Angeles) plus country- and water-body-aware climatology for the rest of the world (with overrides for Arctic, Persian Gulf, Red Sea, Black Sea, and Hormuz). Density is computed with UNESCO-80 and used directly in hydrostatic displacement, so freshwater-vs-saltwater corrections stay accurate per port. ### Updates [#updates-2] * **Layer**: Microsoft Entra ID now reads each user's `signInActivity.lastSignInDateTime` and flags accounts inactive for 90+ days, so dormant identities surface ahead of an [access review](/layer/access-reviews) or scheduled offboarding without a directory export. * **Layer**: Sweeping dashboard polish wave on [app.axiomlayer.io](https://app.axiomlayer.io) — collapsible grouped sidebar (Discover / Finance / Operations / Account) with persisted state and a max-width content area, normalized `PageHeader` across every page, four-card stats strips on Apps / Contracts / Renewals, recharts-backed charts replacing hand-rolled SVGs on Spend detail and Benchmarks, loading skeletons matching the actual layout of Spend / Licenses / Contracts / AI Usage / Benchmarks / Assets / Audit, and a ⌘K command palette synced with the new sidebar groups. See the [May 8 daily entry](/changelog/2026-05-08). ### Fixes [#fixes-3] * **Overwatch**: Production sweep — webhook URL validation on [alert channels](/overwatch/api/alerts) now rejects internal hostnames, link-local ranges, and other non-routable destinations; security headers on [axiomoverwatch.io](https://axiomoverwatch.io) and internal cron auth were tightened across ingestion, archival, alert delivery, and Locus portfolio refresh; and the public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint now returns underlying error details instead of collapsing to a generic 500. * **Overwatch**: Course-alteration worker is now self-observable — a new monitor raises a `worker_inactive` alert when no `course_alteration` events have landed in the trailing 7 days, instead of silently leaving the [Ghost Vessels](/overwatch/api/alerts) inference cron with no input. Alerts auto-resolve as soon as events resume. Stale `pg_cron` schedules pointing at deleted Edge Functions were also retired with a reusable detector so future drift surfaces immediately, and the MPO TIP scout now distinguishes silent upsert failures from idempotent no-ops. * **Overwatch**: [Course-alteration anomaly](/overwatch/api/risk) detection is now actually running in production. The detector that emits `course_alteration` events for 45°+ heading deviations more than 10 km from any port had been wired into a path the production worker never executed, so no events had ever landed in the live [vessel risk](/overwatch/api/risk) feed or the [unified alerts inbox](/overwatch/api/alerts). Detection now runs on every AIS tick, with a `course_alterations_detected` counter exposed in the worker's heartbeat. Forward-only — no backfill. * **Codex**: The [envelope coverage dashboard](/codex/envelope-coverage) refresh no longer times out on tables above one million rows. Tables above that threshold (primarily `ais_positions`) are now sized from the live row-count statistic rather than an exact `COUNT(*)` scan, so the nightly refresh completes cleanly. Coverage numbers for smaller tables are unchanged. * **Overwatch**: Cold [archive](/overwatch/data-retention#archive-storage) credential handling is hardened — surrounding whitespace is trimmed and credentials containing control characters fail fast with a clear configuration error instead of stalling historical-position archival with an opaque runtime failure. * **Overwatch**: Retryable failed [vessel enrichment](/overwatch/api/vessels) queue rows that hadn't exhausted their attempt budget are now reset back to pending automatically, so transient Equasis errors no longer leave otherwise-resolvable vessels parked in the failed bucket. * **Layer**: The Apps, Assets, dashboard, and **Cost per employee** pages on the [Layer dashboard](https://app.axiomlayer.io) are populating again after a row-level security regression that had silently zeroed every read for these views. The pages had been rendering empty even with intact inventory and spend data; reads now flow through the corrected tenant-resolution path and the previously empty rollups, app lists, and asset tables surface their full contents on next load. * **Layer**: The public marketing surface and the sign-in / sign-up pages on the [Layer dashboard](https://app.axiomlayer.io) now render a recovery screen with a **Try again** button when an unexpected server error occurs, instead of leaving the browser stuck on a blank page after a closed render stream. * **Layer**: Sentry **Session Replay** is now disabled on every authenticated route in the [Layer dashboard](https://app.axiomlayer.io) and stops cleanly on client-side route transitions, so tenant data never enters a replay buffer even on long-lived single-page navigations. * **Layer**: Tightened the production [Layer dashboard](https://app.axiomlayer.io) Content-Security-Policy — `'unsafe-inline'` and `'unsafe-eval'` are no longer permitted in `script-src` outside local development, closing a class of script-injection paths without affecting any user-facing functionality. * **Layer**: The cross-product marquee on the [Layer marketing site](https://axiomlayer.io) no longer overflows the viewport on mobile. * **Drift**: Tightened the production Content-Security-Policy on [Drift](https://axiomdrift.io) — `'unsafe-inline'` and `'unsafe-eval'` are no longer permitted in `script-src` outside local development, `frame-src` is now `'none'` so the dashboard cannot embed third-party iframes, and `base-uri`, `object-src`, and `frame-ancestors` are also locked down. No user-facing behavior changes; analytics, billing, and the provider integrations powering shadow-IT discovery continue to work unchanged. * **Drift**: Per-IP rate limits on the [Drift](https://axiomdrift.io) ingest webhook, manual connection creation, and sync endpoints now key on the trusted platform-supplied client IP instead of the raw `X-Forwarded-For` header, so a spoofed forwarding header can no longer be used to evade per-IP throttling. * **Drift**: Dashboard reads on the [Drift](https://axiomdrift.io) Apps, Benchmarks, dashboard, Inventory, and Renewals pages now query the canonical workspace identifier instead of a stale legacy column, so paid workspaces no longer see an empty inventory or zeroed spend totals after the recent multi-tenant migration. * **Layer**: Connection connect and disconnect events on the [integrations page](/layer/integrations/overview) now record the trusted platform-supplied client IP in the [audit log](/layer/audit-log) instead of the raw `X-Forwarded-For` header, so admins reviewing audit entries see an IP that can't be spoofed by a forwarded-header rewrite. * **Codex**: The **RouteShift** entry in the cross-product navigation bar on [axiomcodex.io](https://axiomcodex.io) now points to [routeshift.io](https://routeshift.io) instead of an unowned `.com` domain, so clicks from Codex no longer dead-end. The brand mark in the bar was also refreshed to match the canonical RouteShift glyph. ## Week of April 26–May 2, 2026 — Overwatch terminal, COLREGS encounter analytics, aircraft tracking, public Locus rankings, Layer AI Usage [#week-of-april-26may-2-2026--overwatch-terminal-colregs-encounter-analytics-aircraft-tracking-public-locus-rankings-layer-ai-usage] ### New features [#new-features-4] * **Overwatch**: New Bloomberg-style [terminal](/changelog/2026-05-02-weekly) at `/dashboard` with two preset modes — **TRADE** for commodity flow tracking and **SANC** for sanctions analytics — laying out 12 live-data panels with `F1`–`F12` shortcuts and a `⌘K` command palette. The previous landing is preserved at `/dashboard/overview`. * **Overwatch**: Built-in service [status page](/overwatch/status-page) showing real-time health for database, AIS data freshness, ingestion, and visit pipelines, with a 24-hour timeline and a programmatic health endpoint. * **Overwatch**: New public [`/api/v1/positions/latest`](/overwatch/api/vessels) endpoint returns a global GeoJSON `FeatureCollection` of the latest position for every tracked vessel (\~18K) in a single request — no auth, CDN-cached, with optional `type` and bounding-box filters. * **Overwatch**: Multi-recipient verified email delivery on [alert channels](/overwatch/api/alerts). Up to five recipient addresses per channel, each gated by a one-time confirmation link with a 24-hour expiry, with per-pair cooldowns and daily caps so the channel can't be used as a phishing relay. * **Overwatch**: Per-vessel ETA and route-waypoint [forecasts](/overwatch/api/forecasts) now have a dedicated **Expected Arrivals** dashboard panel listing vessels forecast to arrive in a rolling 7-day window, plus a new `/dashboard/[port]/voyage-times` page rendering per-visit stacked bars (approach / anchor wait / berth / idle other), median summary cards, and a 50-row drill-down table. * **Overwatch**: Daily ingestion of 41 [FRED](https://fred.stlouisfed.org/) economic series — rates, industrial production, capacity, orders, inventories, housing, freight, commodity prices, CPI/PPI, employment, trade, and financial conditions — with vintage-aware observations so historical queries are reproducible. * **Overwatch — historical implementation report; [current confirmation is AIS-only](/overwatch/methodology/chokepoint-transits#current-operating-boundary)**: This release reported persisted Sentinel-1 detections from dark-fleet verification runs. The current [Sentinel endpoint](/overwatch/api/sar-coverage) reports catalog metadata only and does not run vessel detection or confirm dark events. * **Overwatch**: New [vessel density dashboard](/overwatch/getting-started) at `/dashboard/density`. Daily H3 res-8 layer over the last 30 days of AIS positions, filterable by vessel type, with per-IMO-per-hour bucketing so high-frequency pingers don't dominate. Same data exposed at `GET /api/v1/density?type=…&day=YYYY-MM-DD`. * **Overwatch**: Course-alteration anomalies now flow into the [vessel risk](/overwatch/api/risk) event stream — `course_alteration` events fire when an underway vessel turns 45° or more off its 6-hour mean heading more than 10 km from any port zone, with a 6-hour per-vessel dedup window so a sustained turn produces one event rather than a flood. * **Overwatch**: Aircraft tracking is live as a sibling surface to vessel sanctions — hourly ADS-B ingestion for sanctioned airframes (seed coverage now spans Mahan Air, Qeshm Fars Air, Pouya Air, Air Koryo, and Cham Wings / Fly Cham across IRGC-QF, EO 13382, UN 1718, and Syria SDN designations) and a cross-modal lead when a sanctioned aircraft lands within 200 km of a high- or critical-tier dark vessel event. * **Overwatch**: [Pairwise encounter extraction](/overwatch/methodology/encounter-extraction) — vessel-to-vessel CPA, TCPA, range, closing speed, and bearing-rate geometry derived from raw AIS — now runs hourly in production with stable upsert keys for idempotent re-runs, and a new backfill driver fills any historical window. Encounter-derived fields on the [Risk](/overwatch/api/risk) and [Investigations](/overwatch/api/investigations) APIs see fresher coverage as a result. * **Overwatch**: Every encounter epoch now carries COLREGS-aligned **rule posteriors** (head-on / overtaking / crossing) and per-vessel **role posteriors** (give-way / stand-on) derived from epoch geometry alone. Clean geometry pushes the matching rule posterior past `0.85`; ambiguous geometry produces a soft mixture instead of a brittle vote. See [Rule and role posterior inference](/overwatch/methodology/encounter-extraction#rule-and-role-posterior-inference). * **Overwatch**: New **Rule 17 deviation flags** on [pairwise encounters](/overwatch/methodology/encounter-extraction) — each vessel is flagged when its mean stand-on probability across the encounter is at least `0.6` *and* its largest single-step course change is `10°` or more, surfacing stand-on vessels that took unilateral evasive action that COLREGS Rule 17 only authorizes when the give-way side has clearly failed to keep clear. * **Overwatch**: New **Rule 17 handoff timestamp** on [pairwise encounters](/overwatch/methodology/encounter-extraction) records the exact moment Rule 17(a) "keep course and speed" authority transitions to Rule 17(b)/(c) "may / must take avoiding action," tagged as either give-way inaction or in-extremis geometry. Useful for distinguishing premature unnecessary deviation from required avoidance. * **Overwatch**: New **COLREGS compliance scoring** in a sibling `colregs_encounters` table. Every non-compliant encounter gets a `compliance_deficit_nm` — a counterfactual lateral distance between the give-way vessel's actual position at CPA and where it should have been under the minimum-effort compliant maneuver — alongside the resolved encounter type, give-way and stand-on IMOs, the required starboard alteration, and both vessels' actual Δcourse. A new hourly Edge Function lands at minute `:17`, ten minutes after encounter extraction; a 6-hour-window backfill driver fills history. See [COLREGS compliance scoring](/overwatch/methodology/encounter-extraction#colregs-compliance-scoring). * **Overwatch**: New public per-vessel [`/api/v1/ais/{provider}/{imo}/location/latest`](/overwatch/api/vessels) endpoint — citable URL, no API key, IP-keyed at 60/min and 1,000/day, with a JSON-LD attribution block so AI ingestion pipelines pick up the source claim cleanly. * **Locus**: New free, fully-unlocked [Fastest-Growing Neighborhoods (Population)](/locus/mcp-server) ranking sourced directly from U.S. Census ACS 5-year estimates. The existing composite list is now disambiguated as **Fastest-Growing Neighborhoods (Axiom Composite)**. * **Locus**: New free, fully-unlocked [Most Building Permits Issued (Last 12 Months)](/locus/mcp-server) ranking sourced from municipal open data (1.2M permits across 10 metros) and cross-referenced with the U.S. Census Building Permits Survey. * **Locus**: Four more free, third-party-cited public rankings — [Most Appreciated Real Estate](/locus/mcp-server) (FHFA HPI), [Highest Mortgage Activity](/locus/mcp-server) (HMDA), [Lowest Crime Rate](/locus/mcp-server) (FBI UCR / NIBRS), [Best Public Schools](/locus/mcp-server) (NCES CCD), and a [Most Parks](/locus/mcp-server) ranking on the curated POI catalog. * **Locus**: New **Council Activity** card on every [metro pulse page](https://locus.axiomancer.io/pulse) showing 90-day high-signal council meetings, rezonings approved, new-construction approvals, housing units mentioned, and dollar amounts — sourced from the [civic intelligence dataset](/codex/schemas/civic-intelligence). Live for SF, Chicago, and Houston. * **Locus**: Four new live public stats on every [metro pulse hero](https://locus.axiomancer.io/pulse) — *Population Δ*, *Home Price Δ*, *Median Household Income*, *Median Gross Rent* — sourced from Census ACS B19013, B25064, and the FHFA HPI. The 8-signal grid and metro composite are now Analyst+ teaser+blur, while the public stats hero stays free. * **Locus**: New **Maritime → CRE port-risk** propagation surfaces a port-congestion warning on cell detail panels when a Locus metro's primary or secondary port is showing elevated wait times in [Overwatch](/overwatch/api/disruptions). Twenty-two metros mapped to major US ports by trucking corridor. * **Locus**: Top movers on the [signed-in dashboard](https://locus.axiomancer.io/dashboard) split into side-by-side **Risers** and **Decliners** panels. * **Locus**: 12-month permit-trend chart added to the [explorer Intelligence Rail](https://locus.axiomancer.io/explore). * **Locus**: Saved searches and a per-row **+ Portfolio** action on [discover](https://app.axiomlocus.io/discover). Persist any filter set as a named search, jump back via `?saved=`, and add result rows to a [portfolio](/locus/api/portfolios) in one click. A **Saved Searches** panel on the dashboard lists the six most recent. Anonymous visitors see `/discover` unchanged. * **Locus**: Per-portfolio **asset class** on [portfolios](/locus/api/portfolios) — tag any portfolio with one of the seven baked-in [scoring profiles](/locus/scoring-conventions#scoring-profiles) (`general`, `qsr`, `retail`, `office`, `industrial`, `self_storage`, `data_center`) at create time or via inline picker on the detail page, and Locus automatically scores every member under the matching weight profile. Pairs with a new **`/api/score-comparison`** endpoint that returns composite + per-signal-group scores under any combination of profiles in one round-trip, so side-by-side comparisons surface how the same location reads as office vs. retail vs. industrial without N calls to `/api/score`. * **Layer**: New [AI Usage](/layer/ai-usage-tracking) entry in the dashboard sidebar, with a one-click handoff to [RouteShift](https://routeshift.io) — the LLM proxy gateway powering Layer's AI cost tracking — for per-employee keys, smart routing, savings, and live analytics across OpenAI, Anthropic, Google, and other providers. * **Locus**: Curated [ranking lists](/locus/mcp-server) now render the columns that drive each list's sort, with the primary metric featured in big-number style. Each list also gained an attribution footer linking to the underlying [methodology](/locus/scoring-conventions). * **Locus**: The [rankings index](/locus/mcp-server) is now split into **Public Data — Free** (full top 25 for everyone) and **Axiom Composite — Analyst+** (top 3 preview free, full list on the $49/mo Analyst tier). Paywall is enforced server-side, with an unlock card after preview rows on each composite list page. * **Locus**: The [explore](https://locus.axiomancer.io/explore) map now shows a single national activity heatmap aggregated from the last 90 days of geocoded events, replacing the metro-scoped overlay. * **Locus**: Intelligence Rail on the [explorer](https://locus.axiomancer.io/explore) is now cell-aware — click a hex to pin a Selected-cell panel with a 90-day score sparkline, a signal contribution waterfall ranking the eight signal groups (each row click-throughs to its [signal group](/locus/scoring-conventions) detail page), and metro-scoped monitor filtering. A metro key-stats strip (composite avg, GDP YoY, top-scoring signal) sits above the rail. * **Layer, Codex, Platform**: Branded OpenGraph and Twitter `summary_large_image` social preview cards on [axiomlayer.io](https://axiomlayer.io), [axiomcodex.io](https://axiomcodex.io), and [axiomancer.io](https://axiomancer.io). * **Layer, Codex, Platform**: `robots.txt` and `sitemap.xml` now served at site root for [axiomlayer.io](https://axiomlayer.io), [axiomcodex.io](https://axiomcodex.io), and [axiomancer.io](https://axiomancer.io). Codex also emits `SoftwareApplication` JSON-LD; Axiomancer Labs embeds Organization JSON-LD with `sameAs` links to all four product domains. * **Platform**: [RouteShift](/routeshift) is now a first-class product alongside Layer, Overwatch, Locus, and Codex in the cross-product navigation bar at the top of every Axiom site, with a matching emerald mark and a card on the [Axiomancer Labs](https://axiomancer.io) Products catalog. One-click access to the LLM proxy gateway from anywhere in the platform. ### Updates [#updates-3] * **Overwatch**: Panning the [live map](/overwatch/getting-started) is now instant — the map loads the full global vessel layer once on first paint and renders every subsequent pan from data already on the client. Positions still refresh every five minutes. * **Overwatch**: Vessel markers on the [live map](/overwatch/getting-started) now use elongated, bow-forward triangles matching the industry-standard silhouette on VesselFinder and MarineTraffic. * **Overwatch**: All 40+ [dashboard](/overwatch/getting-started) sub-pages and shared chrome — sidebar, mobile nav, global search, port selector — now share the obsidian-and-amber palette of the new terminal. * **Overwatch**: The default homepage hero map moved from the Bosphorus Strait to the Port of Long Beach. * **Overwatch**: AIS [downsampling](/overwatch/data-retention) catches up faster — each run processes up to five days per tier. Positions older than 90 days are now served from the cold archive; live database tiers top out at 90 days. See [Archive storage](/overwatch/data-retention#archive-storage). * **Overwatch**: \~16,000 historical vessel visits backfilled with hydrostatic [cargo estimates](/overwatch/methodology/cargo-validation). * **Overwatch**: Equasis [vessel enrichment](/overwatch/api/vessels) now surfaces ISM Manager, Commercial Manager, and Technical Manager as separate fields, with a distinct relation per role on the vessel relationship graph. The legacy `ship_manager` field is unchanged. * **Overwatch**: Cross-product navigation bar now appears consistently on every page, including intelligence, blog, pricing, and dashboard sub-pages. * **Overwatch, Locus, Platform**: Faster first paint across [axiomoverwatch.io](https://axiomoverwatch.io), [locus.axiomancer.io](https://locus.axiomancer.io), and [axiomancer.io](https://axiomancer.io) via Mux preconnects, hero poster preloads, smaller LCP poster sizes, and deferred PostHog initialization. * **Layer**: Server-rendered marketing hero text on [axiomlayer.io](https://axiomlayer.io) — the headline now paints immediately instead of waiting on client hydration. Cost-rollup endpoints in the dashboard also set `Cache-Control: private, no-store` so per-employee, hardware, and AI cost data can never be served from a CDN cache to the wrong tenant. * **Locus**: Free Location Report requests on [locus.axiomancer.io](https://locus.axiomancer.io) now require a Cloudflare Turnstile CAPTCHA and recipient email confirmation (24-hour link expiry) before a report is generated and sent, with per-IP and per-recipient daily rate limits as a backstop. * **Locus**: New **Permit Scope Quality** sub-score in the `developmentPipeline` signal group on `/api/score`, weighting each recent permit by LLM-extracted `scope_type` (new construction vs. renovation vs. repair, etc.) and `estimated_cost_tier`. Surfaces as `source: "AXL-108"` in the group's `subScores`. See [Development pipeline sub-scores](/locus/scoring-conventions#development-pipeline-sub-scores). * **Locus**: Default `general` [scoring profile](/locus/scoring-conventions#scoring-profiles) on `/api/score` rebalanced to align signal weights with peer-reviewed CRE price-correlation literature — developmentPipeline, economicStrength, and accessibility weighted up; businessVitality, populationMomentum, demographics, and amenityDemand weighted down. Use-case profiles (`qsr`, `office`, `industrial`, `retail`, `data_center`, `self_storage`) are unchanged. Pin to the previous behavior with `profile_version` for replicable historical scores. * **Locus**: Cell scoring now supports per-metro H3 resolution. Ten low-density metros — Phoenix, Houston, Las Vegas, Dallas, San Antonio, Nashville, Jacksonville, Oklahoma City, El Paso, Fort Worth — are now scored at H3 r7 instead of the default r8. See [Per-metro resolution overrides](/locus/scoring-conventions#per-metro-resolution-overrides). * **Locus**: New **Permit Scope Quality** sub-signal in the [development pipeline](/locus/scoring-conventions) score. Each cell now reflects *what* was permitted, not just how many — new construction weighs more than additions, additions more than renovations, renovations more than repairs, with a separate cost-tier multiplier layered on top. Wired into the existing 6-month permit window at 10% weight inside the development pipeline group; other sub-signals are unchanged. ### Fixes [#fixes-4] * **Layer**: Workspaces auto-provision on first dashboard load, on the [integration](/layer/integrations/overview) OAuth connect callback, and on the free [shadow IT scan](/layer/integrations/google-workspace) submission, so first-touch flows complete cleanly without "Unauthorized" or `no_tenant` dead-ends. * **Layer**: Email/password sign-ups that included a workspace name now succeed end-to-end after a regression in the workspace-provisioning trigger was rolling back accounts. Sign-up errors now also show the underlying reason inline. * **Layer**: Connecting an [integration](/layer/integrations/overview) right after sign-up no longer fails with a `save_failed` redirect — the OAuth callback writes through a tenant-authoritative path so brand-new workspaces are recognized on the first connect attempt. Connector tiles also now show the right logo for Microsoft, AWS, Jamf, JumpCloud, and the rest of the catalog. * **Layer**: New users without a workspace now go through an explicit **Create your workspace** step instead of having a workspace auto-named from their email domain — closing a tenant-hijack edge case on invitee and SSO flows. See [Getting started](/layer/getting-started). * **Layer**: Connector tiles on the [integrations](/layer/integrations/overview) catalog now flip to **Connected** the moment an OAuth callback or credential save completes, instead of waiting for a session refresh — newly-connected integrations were briefly displaying as unconnected even after the credential was saved. * **Layer**: Failed Stripe payments now flip the relevant subscription to **past\_due** after three consecutive failed attempts on [Plans and billing](/layer/billing), restoring an `invoice.payment_failed` lifecycle hook that briefly went silent during the recent webhook consolidation. * **Locus**: Neighborhoods on cell [enrichment](/locus/api/enrichment), [scoring](/locus/scoring-conventions), and [location lookups](/locus/api/location-data) now resolve to the names you'd recognize from Google Maps — *SoHo*, *Williamsburg*, *Mission District* — instead of administrative subdivisions. NYC coverage was also restored after the upstream NYC Open Data feed was withdrawn, and multi-part polygons now preserve islands and exclaves. * **Locus**: [Cell scoring](/locus/scoring-conventions) no longer fabricates a "Safe" badge or a 0/100 permit-activity score when the underlying data is missing. [Safety scores](/locus/scoring-conventions) also no longer read 100/100 from a FEMA flood zone alone — the safety group now requires at least two sub-signals before producing a number. * **Locus**: Tiny tracts no longer dominate the public [Fastest-Growing by Population ranking](/locus/mcp-server) — census tracts with fewer than 1,000 prior residents are now filtered out so small-denominator anomalies (e.g., 62→2,382 = +3,741%) don't push genuinely fast-growing inhabited neighborhoods off the leaderboard. Column labels were sharpened to clarify the metric is a roughly 5-year ACS delta. * **Locus**: Cell [score history](/locus/api/discovery-and-intelligence) writes restored after a month-long silent freeze — the daily scorer was upserting a column that only existed on `cell_scores`, so every history write was being rejected and quietly swallowed. The 90-day trajectory sparkline on the [Explorer](/locus/explorer#selected-cell)'s selected-cell panel had been falling back to its dashed *(estimated)* stand-in during the freeze; real time-series data starts populating from the next scorer run forward, and the silent error handler has been replaced with explicit logging so future schema drift surfaces immediately. * **Locus**: Signing in now drops you on the authenticated dashboard at `/dashboard` instead of the [explorer](https://locus.axiomancer.io/explore) map. * **Locus**: Hardened budget caps on the pipelines that refresh [POI inventory](/locus/scoring-conventions#data-freshness) for Locus scoring, with explicit per-key Google Places, weekly global, and Yelp monthly caps under each free-tier ceiling. * **Overwatch**: [Vessel enrichment](/overwatch/api/vessels) from Equasis now warms the session on fresh logins as well as re-logins, eliminating the first-vessel-of-batch failures that accounted for nearly all recent enrichment errors. * **Overwatch**: [AISHub bulk ingestion](/overwatch/ais-coverage) now writes positions in 250-row chunks instead of one statement, so dense corridor fetches (NW Europe / Channel, Strait of Hormuz) no longer trip the database's 60-second statement timeout and lose the entire batch. `ingestion_logs.status` gained a new `'partial'` value for runs where some chunks landed and others failed, with the per-chunk failure count surfaced as `metadata.chunks_failed`. * **Overwatch**: Live map controls no longer clip on shorter or mobile viewports — the map now sizes to `100dvh` and trail controls and the legend respect the safe-area inset. * **Overwatch**: Stale-data-source alerts on the [status page](/overwatch/status-page) now clear automatically as soon as the source recovers, including for slower feeds running less than every six hours. * **Overwatch**: More resilient ingestion of cultural amenity data from OpenStreetMap — records with freeform `start_date` values like `"1870"` or `"c. 1900"` no longer fail to load. * **Overwatch**: Brazilian ANTAQ vessel-call ingestion no longer silently strands existing rows without cargo tonnage. Tonnage now flows into the [cargo validation](/overwatch/methodology/cargo-validation) pipeline as soon as the upstream archive is reachable, and any future fetch failure surfaces on the [status page](/overwatch/status-page) instead of disappearing into a console warning. * **Codex**: In-app support chat fonts now load cleanly on [axiomcodex.io](https://axiomcodex.io) — the Intercom font subdomain has been added to the CSP allowlist. * **Codex**: Tightened the Content-Security-Policy on [axiomcodex.io](https://axiomcodex.io) to drop `unsafe-eval` from `script-src`, closing a class of script-injection paths without affecting any user-facing functionality. * **Layer**: Scheduled reports no longer double-send when the cron loop runs twice in the same window — each scheduled send is claimed exactly once per `(schedule, scheduled-for)` window, so a Vercel cron retry, manual overlap, or multi-region replica race cleanly skips instead of re-emailing recipients. ## Week of April 19–25, 2026 — Layer GA, Overwatch reliability, civic data fixes [#week-of-april-1925-2026--layer-ga-overwatch-reliability-civic-data-fixes] ### New features [#new-features-5] * **Layer**: Major release across the SaaS lifecycle. New surfaces include the [audit log](/changelog/2026-04-25), AI spend tracking, virtual cards with per-vendor caps, monthly and annual spend budgets, SaaS benchmarks, license management with seat harvesting, access reviews, multi-stage access approval workflows, AI contract extraction, a renewal calendar, automated offboarding, an onboarding readiness tracker, device shipping with carrier tracking, a [compliance readiness dashboard](/changelog/2026-04-25), webhook notifications, custom fields, scheduled reports, and global search. * **Layer**: New [MCP server](/changelog/2026-04-25) lets AI assistants query your asset inventory, discovered apps, controls, and platform counts. * **Layer**: Free no-signup [shadow IT scan](/changelog/2026-04-25) for [Google Workspace](/layer/integrations/google-workspace) — discovers up to 50 apps in under five minutes. * **Layer**: Axiom Layer Precision browser extension tracks active versus passive SaaS usage on managed devices. * **Layer**: Plan-tier limits are now enforced at runtime, with in-context upgrade banners and rate-limit headers on `/api`. See [Plans and billing](/layer/billing). * **Overwatch**: Built-in [status page](/overwatch/status-page) showing real-time health for database, AIS data, and pipeline services, plus a programmatic `/api/health` endpoint. * **Codex**: New port authority governance dataset covering Oakland, Long Beach, Los Angeles, JAXPORT, and the Port Authority of New York and New Jersey. * **Codex**: All 111 tables now carry the full [APRS envelope](/codex/normalization-standard); coverage is enforced in CI and tracked on the [envelope coverage dashboard](/codex/envelope-coverage). * **Locus**: In-app support chat, with identity verification when signed in. ### Updates [#updates-4] * **Overwatch**: Default AIS coverage radius expanded from \~55 km to 220 km per port, with an opt-in [global tracking flag](/overwatch/ais-coverage) for dark-fleet and open-ocean monitoring. * **Overwatch**: New tiered [AIS data retention](/overwatch/data-retention) policy — full resolution for 7 days, thinned to one position per minute through 30 days, archived to cold storage thereafter. * **Overwatch**: Vessel markers on the [live map](/overwatch/getting-started) replaced with rotated triangle icons that read as bow-forward at every zoom. * **Overwatch**: \~16,000 historical visits backfilled with hydrostatic [cargo estimates](/overwatch/methodology/cargo-validation). * **Layer**: Dashboard persona setting (Finance, IT, or Both), hardware lifecycle settings, and a shadow app review queue with explicit approve/reject flow. * **Layer**: Brand accent refreshed from amber to pink across the [Layer marketing site](https://axiomlayer.io) and dashboard; cross-product bar updated everywhere to match. * **Codex / Locus**: NYC [council decisions and zoning variances](/codex/schemas/civic-intelligence) are now populated, with a Legistar HTML fallback when the JSON API misses fields. Federal NEPA environmental reviews are now flowing in via the Federal Register. * **Codex**: Faster APRS backfill (5x) for the largest legacy datasets — projected completion now under 60 days. Restored [NTD transit ridership](/locus/scoring-conventions) data and improved data quality in NFIP and HMDA. * **Locus**: Refreshed social previews and sharper page titles on [locus.axiomancer.io](https://locus.axiomancer.io); the [signals](https://locus.axiomancer.io/signals) page now reads counts directly from the live catalog. Primary fonts are also self-hosted now, removing a render-blocking request and the brief flash of unstyled text on first load. * **Platform**: Cross-product bar inactive labels lifted to WCAG AA contrast, and the **Docs** link is now product-aware on every site. ### Fixes [#fixes-5] * **Locus**: [Cell scoring](/locus/scoring-conventions) writes restored after upsert errors were being swallowed; scores, [rankings](/locus/api/analytics), and downstream queries are flowing again. * **Locus**: Walkability scoring restored after the upstream OpenStreetMap provider began rejecting requests without a User-Agent. * **Locus**: Code enforcement collection now uses a 7-day window matching its weekly cadence, so updates no longer time out. * **Overwatch**: More reliable Equasis vessel enrichment (concurrent relay, full session re-warm) — registered owner, flag state, and deadweight tonnage populate consistently. * **Overwatch**: Daily [risk-scoring](/overwatch/api/risk) feature generation restored after a column-mismatch failure; ship-to-ship transfer history and identity-change events stay current. * **Overwatch**: Port-call and [disruption](/overwatch/api/disruptions) processing now uses smaller batches and per-query timeouts, eliminating OOMs and 504s during load spikes. * **Overwatch**: Flag-hopping detection now records all flag changes; client-side crash on first load resolved; first-time-seen and shared-MMSI vessels no longer drop position updates. * **Overwatch**: AIS positions ingested from AISHub now populate `h3_index` at write time, restoring 100% coverage on the [envelope dashboard](/codex/envelope-coverage) and unblocking spatial joins on the full [`ais_positions`](/codex/schemas/ais-maritime) table. * **Layer, Locus, Overwatch**: Marketing pages and the cross-product bar now meet WCAG AA contrast across hero copy, footers, inactive product labels, and the [Layer](https://axiomlayer.io) "Get started" CTA. Locus and Overwatch homepages — plus the [Locus pricing page](https://locus.axiomancer.io/pricing) and all eight Locus content pages (blog, pulse, docs, methodology, sources, [explore](https://locus.axiomancer.io/explore), [signals](https://locus.axiomancer.io/signals), rankings) — also expose proper `

` landmarks for screen readers. The shared Locus content footer used across pricing, blog, pulse, and docs was lifted past AA contrast in a final follow-up. * **Layer, Locus, Overwatch**: Brand colors and Docs link fallbacks aligned across all four sites — the cross-product bar uses pink for Layer and indigo for Locus everywhere, and the **Docs** link falls back to the product's own docs section. * **Layer**: Slack bot tokens are now exclusively encrypted at rest; virtual card operations verify cardholder ownership; multiple rounds of security hardening across authentication, RLS, idempotency, and rate limiting. * **Layer**: Content Security Policy now allows the providers the dashboard depends on — Intercom for in-app chat, Mux for embedded video, and the analytics stack — so the support widget loads reliably and tracked events are no longer dropped on browsers enforcing strict CSP. ## April 18, 2026 — Stripe billing + 6 new connectors + catalog cleanup [#april-18-2026--stripe-billing--6-new-connectors--catalog-cleanup] * **Layer**: Stripe billing wired end-to-end. New `/settings/billing` page lets users pick Starter/Growth/Scale tiers (monthly or annual), open the Stripe Customer Portal, and see their current subscription. Webhook reconciles `checkout.session.completed`, subscription updates, cancellations, and dunning back to the `subscriptions` table (LAY-255). * **Layer**: 6 high-value connectors promoted from "legacy stub" to first-class discovery — **AWS** (native Sigv4 signing replaces broken legacy code), **GCP** (service-account JWT-bearer auth), **Azure** (OAuth2 client\_credentials), **GitHub**, **CrowdStrike**, **Datadog**. All return assets + structured evidence with control-code mappings (LAY-251). * **Layer**: Hid 43 stub connectors from the integrations catalog — only end-to-end working integrations show up now. Added a "Request a connector" CTA so customers can express demand for the rest (LAY-250). ## April 18, 2026 — Intercom across the platform + analytics provider rollout [#april-18-2026--intercom-across-the-platform--analytics-provider-rollout] * **All sites**: Intercom Messenger now lives on every Axiom property (Layer app, Overwatch, Locus, Codex, Axiomancer, docs). Marketing visitors hit the same workspace anonymously; Layer signs them in with a server-minted JWT once they're authenticated, so support sees a single conversation history per identity. * **All sites**: PostHog + Amplitude + Sentry providers wired uniformly across the 4 marketing sites (parity with Layer). * **docs.axiomancer.io**: Native Mintlify Intercom integration enabled — no client-side script required. ## April 18, 2026 — Audit log + connector audit + Codex evidence catalogs [#april-18-2026--audit-log--connector-audit--codex-evidence-catalogs] * **Codex**: New evidence catalog pages for [ISO 27001](/codex/iso27001-evidence-catalog), [HIPAA](/codex/hipaa-evidence-catalog), and [PCI DSS](/codex/pci-dss-evidence-catalog) — per-control API references showing exactly what evidence Codex collects. * **Codex**: New framework guides for [NIST 800-53](/codex/nist-800-53), [SOC 1](/codex/soc1), and [FedRAMP](/codex/fedramp). * **Layer**: Empty-state pitch on `/integrations` — when no integrations are connected, surface a "get started in 2 minutes" hero with the recommended first connections. * **Layer**: Onboarding flow now leads with one-click admin-consent OAuth language for Google Workspace and Microsoft 365. No more "API tokens" copy. * **Layer**: Audit log table migration drafted (review pending) — when applied, every integration connect/disconnect, asset mutation, and access change gets logged with tenant scoping. * **Internal**: Connector catalog audit published — 75 catalog entries, \~25 production-ready end-to-end. Backlog tickets filed for the rest. ## April 17, 2026 — Auth0 admin-consent OAuth + Mintlify docs hub [#april-17-2026--auth0-admin-consent-oauth--mintlify-docs-hub] * **Layer**: **Google Workspace** and **Microsoft 365** integrations now use one-click admin-consent OAuth (no GCP project, no Azure AD app registration on the customer side). Same flow extended to Microsoft Intune, Teams, and M365 Mail. * **Layer**: IdP token refresh wired transparently — delegated tokens auto-renew on 401, rotated tokens persist back to the encrypted credential store. Connections survive past the 1-hour Microsoft / Google token TTL without manual re-auth. * **Layer**: Daily integration health email cron (Vercel cron, opt-in via Resend API key). * **Layer**: Connector cards now show real brand icons (simple-icons CDN), translucent placeholder examples in inputs, and hover info tooltips next to each credential field label. * **Layer**: AxiomBar (cross-product nav) now appears on dashboard pages, not just marketing. * **docs.axiomancer.io**: This site went live. Auto-converted Overwatch (70 endpoints) and Locus (35 endpoints) API references; hand-written Layer integration guides for 11 connectors; Codex framework guides for SOC 2 / ISO 27001 / HIPAA. Mintlify-hosted with a free auto-generated [MCP server](https://docs.axiomancer.io/mcp) so AI assistants can search the docs natively. * **Internal**: Tier 2 OAuth scaffolding script (Slack / Notion / Atlassian) — when credentials arrive, wiring is `./wire.sh slack `. ## April 16, 2026 — Polish week [#april-16-2026--polish-week] * **Layer**: Shared `AxiomBar` component pinned to the top of every Axiom site for consistent cross-product nav. * **Layer**: Scroll-reveal animations on integrations, pricing, FAQ sections. * **Layer**: New animation primitives — `Reveal`, `useInView`, `AnimatedCounter`. * **Layer**: Brand mark corrected to the canonical hex-network design. * **Layer**: 4K Mux video on the marketing hero. * **Layer**: Apps page now shows an `EmptyState` instead of redirecting to login when `org_id` is missing. ## April 14, 2026 — UI redesign sprint [#april-14-2026--ui-redesign-sprint] * **Layer**: People, Apps, Spend, Contracts, Renewals all redesigned with consistent metric cards + urgency bars + category filters. * **Layer**: Integrations grid redesigned — colored tiles, status rings, connected-state actions. ## April 12, 2026 — Plans 1–4 shipped (April sprint) [#april-12-2026--plans-14-shipped-april-sprint] * **Layer**: Hardware cost foundation (`hardware_purchase_events` table, amortization engine, `/api/employees/costs` endpoint). * **Layer**: Cost intelligence UI — per-employee cost roll-ups, hardware monthly amortized totals, vendor consolidation. * **Layer**: Lifecycle workflows — onboarding/offboarding cards, MDM lifecycle. * **Layer**: AI usage tracking — per-employee LLM spend tracking via OpenAI / Anthropic admin APIs. * **Layer**: Navigation restructured — People / Apps / Hardware / Settings. ## Earlier [#earlier] For the full project history, see the [GitHub repo](https://github.com/smynkr/axiomlayer) and [Linear](https://linear.app/mcclawd) project tracking. # Audit export package (/codex/audit-export) When your auditor asks for evidence, **Reports → Generate audit package** outputs a structured archive your auditor can ingest directly. This page documents the format so you can answer "what's in here?" before the auditor opens it. ## Top-level archive contents [#top-level-archive-contents] ```text audit-export--.zip ├── README.txt # Cover sheet for the auditor ├── manifest.json # Machine-readable index of every file ├── controls/ │ ├── / │ │ ├── status.json # Current status, last verified, owner │ │ ├── evidence/ │ │ │ ├── .json # Raw API response with timestamp │ │ │ └── ... │ │ └── exceptions.md # Documented exceptions (when applicable) │ └── ... ├── exports/ │ ├── access-review-.csv # Per-user app access at the period end │ ├── terminations-.csv # HRIS termination → IdP deactivation diffs │ ├── changes-.csv # Merged PRs with reviewer + timestamp │ └── incidents-.csv # Incident timeline + post-mortem links └── policies/ ├── information-security-policy.pdf └── ... # Linked from connected docs system ``` ## Per-control structure [#per-control-structure] Each control gets a folder named by the control ID (e.g. `CC6.1` for SOC 2, `A.5.16` for ISO 27001). Inside: ### `status.json` [#statusjson] ```json { "control_id": "CC6.1", "title": "Logical access provisioning", "framework": "SOC 2 (TSC 2017)", "status": "met", "last_verified": "2026-04-17T10:23:00Z", "owner": "alice@axiomancer.io", "evidence_count": 47, "evidence_period": { "start": "2025-10-17T00:00:00Z", "end": "2026-04-17T23:59:59Z" }, "auto_evidenced": true, "exceptions": [] } ``` ### `evidence/.json` [#evidenceevidence-idjson] Each evidence file is a single observation with full provenance: ```json { "evidence_id": "ev_01HXYZ...", "control_id": "CC6.1", "type": "user_provisioning_event", "source": "google_workspace", "source_url": "https://admin.google.com/ac/users/", "collected_at": "2026-04-17T10:23:01Z", "raw_response": { "user_id": "12345", "email": "newhire@axiomancer.io", "creation_time": "2026-04-15T09:00:00Z", "created_by": "alice@axiomancer.io", "org_unit": "Engineering" }, "summary": "User newhire@axiomancer.io provisioned by alice@axiomancer.io on 2026-04-15" } ``` The `raw_response` field is the auditor's friend — it's the actual API response, unmodified, with the timestamp Codex received it. Auditors trust this because it's not editorialized; if a question comes up about a specific event, the auditor can match the `source_url` to the live admin console. ### `exceptions.md` [#exceptionsmd] When a control has documented exceptions (e.g. "this user retained access for 48h post-termination because of a contract negotiation"), they're recorded as Markdown: ```markdown # Exceptions for CC6.1 ## 2026-03-20 — extended access for departing engineer User: bob@axiomancer.io Termination: 2026-03-18 17:00 UTC Deactivation: 2026-03-20 22:00 UTC (53h gap) SLA: 24h (failed by 29h) Justification: Engineer was retained as contractor for knowledge transfer on a customer escalation. Bob's account was demoted to read-only on 2026-03-18 17:30 (within SLA) and fully deactivated after the contract concluded. Approved by: charlie@axiomancer.io (security lead) on 2026-03-19. Risk acceptance: bob's read-only access was monitored via Datadog event log; no anomalous activity observed. ``` ## Aggregate exports (`exports/`) [#aggregate-exports-exports] These are CSVs the auditor can open in Excel/Sheets to scan for patterns. Common asks: | File | What's in it | | ------------------------------ | ------------------------------------------------------------------------------------ | | `access-review-.csv` | One row per (user, app) — current role, last activity, last review date | | `terminations-.csv` | One row per termination — HRIS event, IdP deactivation, gap, exceptions | | `changes-.csv` | One row per merged PR — repo, author, reviewers, merge time, deployed-to-prod time | | `incidents-.csv` | One row per incident — severity, detected, acknowledged, resolved, post-mortem URL | | `vulnerabilities-.csv` | One row per finding — source, severity, discovered, triaged, resolved, SLA met (Y/N) | ## Manifest [#manifest] `manifest.json` is the machine-readable index. Useful when the auditor uses a tool that ingests structured evidence (some now do — common in SOC 2 firms with audit-tech investments): ```json { "framework": "SOC 2 Type II", "generated_at": "2026-04-17T10:23:00Z", "evidence_period": { "start": "...", "end": "..." }, "controls_total": 64, "controls_met": 58, "controls_partial": 4, "controls_missing": 2, "controls": [ { "control_id": "CC6.1", "status": "met", "evidence_count": 47, "evidence_files": ["controls/CC6.1/evidence/ev_01HXYZ...", "..."] } ] } ``` ## Format choices auditors notice [#format-choices-auditors-notice] A few decisions Codex makes that auditors call out positively: 1. **No PDF-only artifacts** — every control has both human-readable status AND machine-readable JSON. Auditors can grep, filter, and aggregate. 2. **Every evidence has a timestamp from Codex's collection** — not "we generated this in March." If the auditor questions a specific date, Codex's collection time is the timestamp of record. 3. **Source links are deep URLs into the source admin console** — the auditor can open Codex's evidence and Google Workspace side by side to verify. 4. **Exceptions are first-class** — Codex doesn't hide failed controls, it surfaces them with documented justification. Auditors prefer companies that admit gaps (and remediate) over companies that paper over them. ## What's NOT in the export [#whats-not-in-the-export] * **Source documents** — your PDFs, contracts, BAA documents are linked from `policies/` or `controls//exceptions.md` but not duplicated. Auditors get separate read-only access to those source systems. * **Personal data** — user names + emails are included where they're material to the control (e.g. who did what, when). Customer PII is never included unless it's specifically the audit subject. * **Source code** — repo metadata (author, reviewer, merge time) is included; source code itself is not. # BAA tracking workflow (/codex/baa-workflow) If you're a HIPAA Business Associate, every vendor that touches protected health information (PHI) on your behalf needs a signed Business Associate Agreement (BAA). When your customer (the Covered Entity) audits you, they'll ask for your BAA inventory. Codex tracks BAAs alongside vendor metadata so that inventory is always current — not a stale spreadsheet your CFO last touched 18 months ago. ## What Codex tracks per vendor [#what-codex-tracks-per-vendor] ```text Vendor: Slack Technologies BAA status: signed ✓ BAA signed date: 2024-08-15 BAA version: Slack Enterprise BAA, v3 Expiration: none (renews with subscription) Document storage: Linked Google Drive PDF (read-only audit access) PHI scope: messages, file attachments Annual review: due 2026-08-15 (next required attestation) Owner: alice@axiomancer.io ``` ## Vendor categories [#vendor-categories] Codex classifies every vendor into one of three buckets: ### 1. PHI-handling — BAA required [#1-phi-handling--baa-required] The vendor processes, stores, or transmits PHI. Examples: * Cloud infrastructure (AWS, GCP, Azure, Cloudflare) * Communication (Slack, Microsoft 365, Google Workspace, Zoom) * Customer support (Zendesk, Intercom, Front) * Analytics where PHI may flow (Mixpanel, Amplitude, Segment) * File storage (Box, Dropbox, OneDrive) * Backup (Datto, Veeam) Codex flags these as BAA-required and prompts you to confirm BAA status. ### 2. Adjacent — BAA not required, due-diligence still useful [#2-adjacent--baa-not-required-due-diligence-still-useful] The vendor doesn't see PHI directly but has access to systems that handle PHI. Examples: * Code repositories (GitHub, GitLab) — code may reference PHI schemas but doesn't store PHI * IaC + CI/CD — Terraform, GitHub Actions, CircleCI * Monitoring without log content (Datadog Metrics, but not Datadog Logs) Codex tracks these with "BAA not required" justification but still expects vendor risk assessment evidence. ### 3. Internal-only — no PHI exposure [#3-internal-only--no-phi-exposure] Pure internal tooling: Linear, Notion (if you don't paste PHI in pages), Figma. No BAA, no risk assessment required. ## BAA inventory workflow [#baa-inventory-workflow] ### Codex auto-discovers vendors [#codex-auto-discovers-vendors] Connectors to your IdP, finance, and email scanner surface every SaaS vendor your company uses. Codex tags each as BAA-required, adjacent, or internal-only based on category + PHI-likelihood heuristics. ### You review and confirm classification [#you-review-and-confirm-classification] Open **Vendors → Review** and override Codex's classification where wrong. Most companies have \~10-15 BAA-required vendors and 30-50 total. ### For each BAA-required vendor, attach the signed BAA [#for-each-baa-required-vendor-attach-the-signed-baa] Upload the PDF (or paste a Google Drive link). Codex extracts the signed date and version. ### Codex sends renewal reminders [#codex-sends-renewal-reminders] For BAAs with expiration dates, reminders fire at 90d / 30d / 7d / 0d before expiry. For BAAs that renew indefinitely with the subscription, Codex sends an annual attestation reminder so a human re-confirms the BAA is still in force. ### Audit export [#audit-export] **Reports → BAA inventory** outputs a CSV + PDF with current status for every vendor. Hand to your customer's audit team. ## What auditors check on a BAA [#what-auditors-check-on-a-baa] When your customer reviews your BAA inventory, they're verifying: 1. **Coverage** — every vendor that touches PHI has a BAA. Codex's classification step surfaces gaps. 2. **Currency** — BAAs are signed and unexpired. Codex's renewal reminders prevent silent expirations. 3. **Scope** — the BAA covers the actual data flow. If you started using a vendor's new feature that handles PHI in a way the BAA doesn't anticipate, that's a gap. 4. **Subprocessor cascading** — if your vendor uses subprocessors (e.g. Slack uses AWS), the BAA must permit that and your vendor must have BAAs with their subprocessors. Codex tracks this transitively when the vendor publishes a subprocessor list. ## What happens when a vendor refuses to sign a BAA [#what-happens-when-a-vendor-refuses-to-sign-a-baa] Some smaller SaaS vendors don't offer BAAs. Three options: 1. **Replace the vendor** with one that signs BAAs (cleanest but expensive). 2. **Eliminate PHI from that integration** — work with the vendor team to confirm only non-PHI data flows. Document this in Codex with the technical control that prevents PHI from leaking. 3. **Accept the risk** — only viable for very narrow exposure with strong customer notification. Codex stores the risk acceptance memo with sign-off from your privacy officer. The third option is rarely the right call. Most enterprise customers will reject a Business Associate that has un-BAAed PHI-touching vendors regardless of memos. ## Common gotchas [#common-gotchas] * **OAuth-installed apps** add new BAA-required vendors silently. If a developer connects PagerDuty to your Slack workspace, PagerDuty is now seeing channel data. Codex's IdP integration discovers OAuth grants and surfaces them as new vendors awaiting classification. * **Free tools used by individual employees** (Grammarly, Calendly, etc.) often lack BAAs. Codex's email scanner detects sign-up confirmations, surfaces the vendor, and prompts the employee to either uninstall or get IT to procure a BAA-eligible plan. * **AI vendors** (OpenAI, Anthropic) require special attention — many enterprise tiers offer BAAs but consumer/individual plans don't. Codex flags AI vendor sign-ups specifically because the PHI risk is so high. # Bitemporal fields (/codex/bitemporal-fields) Public records are inherently temporal, and most normalization failures stem from conflating different time dimensions. This page maps every temporal field Codex emits per dataset, so you never have to guess which clock a timestamp is on. ## Universal fields [#universal-fields] Every Codex record carries up to seven temporal fields where semantically applicable. These extend the [normalization standard](/codex/normalization-standard) bitemporal contract. | Field | Meaning | | ---------------- | ------------------------------------------------------------------------- | | `ingested_at` | When the Codex system first observed the row. Never mutates after insert. | | `modified_at` | When the row was last updated. Refreshed on every write. | | `occurred_at` | When the real-world event actually happened. | | `filed_at` | When the record was filed or submitted to the authority. | | `published_at` | When the source authority published the record. | | `effective_from` | When the record or ruling became legally effective. | | `effective_to` | When it expired or was superseded. Null means currently active. | `filed_at` is distinct from `occurred_at` for records where the filing is itself the event (e.g. SEC filings) versus records where filing follows the event (e.g. a council vote happens, minutes are filed days later). ## Field availability by dataset [#field-availability-by-dataset] | Field | Civic | Events | AIS | USG | LEHD | POI | Permits | OSHA | | ---------------- | :------: | :------: | :------: | :------: | :------: | :------: | :------: | :------: | | `ingested_at` | required | required | required | required | required | required | required | required | | `modified_at` | required | required | required | required | required | required | required | required | | `occurred_at` | required | required | required | — | — | optional | required | required | | `filed_at` | optional | optional | — | — | — | — | required | required | | `published_at` | required | optional | — | — | — | optional | optional | optional | | `effective_from` | optional | — | — | — | — | — | required | — | | `effective_to` | optional | — | — | — | — | — | optional | — | ## Domain-specific temporal fields [#domain-specific-temporal-fields] Some datasets carry additional temporal fields beyond the universal set. ### AIS Maritime — port-call lifecycle [#ais-maritime--port-call-lifecycle] Port calls have four clocks that must not be conflated: | Field | Meaning | Source | | ----- | --------------------------- | ------------------------------------------ | | `eta` | Estimated time of arrival | Vessel-declared (AIS message 5) | | `ata` | Actual time of arrival | Observed from first in-port AIS position | | `etd` | Estimated time of departure | Vessel-declared or port authority schedule | | `atd` | Actual time of departure | Observed from last in-port AIS position | `occurred_at` is set to `ata` for `port.entered` events and `atd` for `port.departed` events. ETA/ETD are retained as separate fields, never overwritten by actuals. Use both to analyze punctuality: ```sql SELECT vessel_name, port_id, (ata - eta) AS arrival_delay FROM port_calls WHERE ata IS NOT NULL AND eta IS NOT NULL; ``` ### Permits — six-stage lifecycle [#permits--six-stage-lifecycle] Each permit record carries up to six stage-specific timestamps. Only `filed_at` is universally present; others are populated as stages complete. | Field | Meaning | | -------------- | ----------------------------------------------------------------- | | `filed_at` | Application filed with the authority (required) | | `applied_at` | Alias for `filed_at` in jurisdictions that use the term | | `approved_at` | Approved by the authority | | `issued_at` | Permit issued or recorded. May differ from `approved_at` by days. | | `inspected_at` | Last inspection, if tracked | | `expired_at` | Expired or withdrawn | `occurred_at` is set to the stage-specific timestamp of the event type — a `permit.filed` event has `occurred_at = filed_at`, a `permit.approved` event has `occurred_at = approved_at`. ### Civic Intelligence — publication lag [#civic-intelligence--publication-lag] For council proceedings, the gap between `occurred_at` (meeting date) and `published_at` (minutes publication) can be days to weeks. Both fields are always populated so you can analyze either event time or public-record time. ### OSHA — case lifecycle [#osha--case-lifecycle] | Field | OSHA source column | Meaning | | ------------- | ------------------ | ----------------------------------------- | | `filed_at` | `open_date` | Inspection opened | | `occurred_at` | varies | Event that triggered inspection | | `modified_at` | `close_case_date` | Case closed, or last update if still open | ## Common pitfalls [#common-pitfalls] Avoid these temporal field mistakes — they are the most common source of data errors in downstream analysis. * **Single-timestamp fallacy.** Do not collapse `occurred_at`, `published_at`, and `filed_at` into one field. They are rarely the same value. * **Using `ingested_at` for event-time analysis.** `ingested_at` is the wrong clock for analysis — use `occurred_at` or the domain-specific actual time. * **Forgetting `modified_at` on updates.** Every writer must refresh `modified_at`. Skipping this breaks incremental-sync consumers. * **Overwriting ETA with ATA.** Overwriting the estimate with the actual loses the punctuality signal. Keep both. * **Confusing `applied_at` and `filed_at`.** Some jurisdictions distinguish these. Codex publishes one or the other per record, never both with different values. ## Example queries [#example-queries] ### Permits filed but not yet approved after 90 days [#permits-filed-but-not-yet-approved-after-90-days] ```sql SELECT id, filed_at, jurisdiction_slug FROM normalized_permits WHERE approved_at IS NULL AND filed_at < now() - interval '90 days'; ``` ### Publication lag distribution for council proceedings [#publication-lag-distribution-for-council-proceedings] ```sql SELECT jurisdiction_slug, percentile_cont(0.5) WITHIN GROUP (ORDER BY published_at - occurred_at) AS p50_lag, percentile_cont(0.9) WITHIN GROUP (ORDER BY published_at - occurred_at) AS p90_lag FROM civic_records WHERE published_at IS NOT NULL AND occurred_at IS NOT NULL GROUP BY jurisdiction_slug; ``` ### Port calls where arrival was more than 12 hours late [#port-calls-where-arrival-was-more-than-12-hours-late] ```sql SELECT vessel_name, port_id, ata - eta AS delay_hours FROM port_calls WHERE ata IS NOT NULL AND eta IS NOT NULL AND ata - eta > interval '12 hours'; ``` # Chunking policy (/codex/chunking-policy) Codex chunks records along structural boundaries (agenda items, speaker turns, permit scopes) rather than fixed token windows. This preserves semantic context and improves retrieval accuracy by 20–40% compared to naive fixed-size chunking on government and legal text. ## Principles [#principles] 1. **Respect source structure.** Chunk at sections, speaker turns, or clause boundaries. Fall back to token-window chunking only when no structure exists. 2. **One chunk = one contract obligation.** Permit conditions, lease clauses, and blocker tags each become their own chunk. 3. **Parent-child friendly.** Every chunk carries `doc_id` + `section_id` so retrievers can fetch the parent document when a chunk matches. 4. **Bounded size.** Target 300–800 tokens for narrative sections; hard cap 1,500 tokens with intelligent split. 5. **Overlap only when needed.** Zero overlap for structured splits. Fixed 50-token overlap only for token-window fallback. 6. **Deterministic IDs.** `chunk_id` is SHA-256-derived via `make_chunk_id(doc_id, section_id)` — re-running the chunker on unchanged text produces identical IDs, enabling incremental vector-index updates. ## Chunk schema [#chunk-schema] Every chunk record has this shape, written to a per-dataset `_chunks` Parquet file alongside the main dataset export. | Field | Type | Description | | ------------------- | --------- | ------------------------------------------------------------------------- | | `chunk_id` | URN | `urn:aprs:chunk:{16-hex}` — SHA-256 of `doc_id` + section. Deterministic. | | `doc_id` | URN | Parent record's APRS URN | | `section_id` | string | Stable section identifier within the document | | `chunk_text` | text | The chunk content | | `chunk_type` | enum | See [chunk types](#chunk-types) below | | `token_count` | int | Token count (tiktoken cl100k\_base) | | `char_count` | int | Character count | | `seq_index` | int | 0-based sequential index within the document | | `parent_chunk_id` | URN | Null for top-level chunks; set for subsections | | `evidence_anchor` | JSON | `{page, char_span, xpath?}` for source verification | | `embedding_model` | string | Embedding model used (e.g. `text-embedding-3-large`) | | `embedding_version` | string | Model version or fingerprint | | `chunked_at` | timestamp | When chunking occurred | | `chunking_version` | string | Version of the chunking policy applied | ## Per-dataset chunking rules [#per-dataset-chunking-rules] ### Civic Intelligence [#civic-intelligence] Source material: council transcripts, agenda items, meeting minutes. Chunk at, in priority order: 1. **Agenda item boundaries** — each item is its own chunk tree. `section_id = "item.{agenda_item_number}"`. 2. **Speaker-turn boundaries** — inside an agenda item, chunk per speaker turn. `section_id = "item.{n}.turn.{m}"`. Turns under 50 tokens are merged with the next turn from the same speaker. 3. **Blocker/condition enumeration** — each blocker tag or condition becomes its own chunk with `chunk_type=condition`. 4. **Contingency DAG nodes** — each node becomes a `chunk_type=contingency` chunk. The parent chunk for an agenda item contains the item summary; each speaker-turn, condition, and contingency is a child with `parent_chunk_id` set. ### Events Timeline [#events-timeline] Each event is a chunk. `section_id` is the event's own ID. `chunk_type=event`. Long event descriptions (e.g. `dark_event` with extensive kinematic detail) split at 800 tokens with 50-token overlap. All splits share the same `parent_chunk_id`. ### Permit Signals [#permit-signals] Two-level tree: 1. **Permit parent** — summary plus APRS envelope. `chunk_type=permit_summary`. 2. **Scope sections** — each LLM-extracted scope section (e.g. "Floor 1 addition", "Mechanical — HVAC") becomes its own chunk with `chunk_type=permit_scope_section`. Each condition in the permit (e.g. "Subject to ADA variance approval") is an independent chunk with `chunk_type=condition` — they are frequently cited in isolation, so joining them with their scope section would hurt retrieval. ### OSHA Safety [#osha-safety] Two-level tree: 1. **Case parent** — `chunk_type=osha_case_summary`. 2. **Citation sections** — one per citation, since OSHA citations are independently enforceable. `chunk_type=osha_citation`. ### AIS Maritime Positions [#ais-maritime-positions] Not chunked. Positions are point-in-time records — one row equals one record. No `_chunks` file for this dataset. ### Urban Signal Grid, LEHD Flows, POI Intelligence [#urban-signal-grid-lehd-flows-poi-intelligence] Structured-only datasets. The `llm_text` Markdown-KV view is the text surface and is already compact (under 400 tokens per record). Each record maps to one chunk with `chunk_type=record_view`. ## Chunk types [#chunk-types] | Type | Description | | ---------------------- | -------------------------------------------------------- | | `event` | Single event row (Events Timeline) | | `record_view` | Markdown-KV view of a structured record (USG, LEHD, POI) | | `agenda_item` | Top-level civic agenda item | | `speaker_turn` | Civic transcript speaker turn | | `condition` | Enforceable condition, blocker, or covenant | | `contingency` | DAG node in a civic contingency chain | | `permit_summary` | Permit root chunk | | `permit_scope_section` | Scope subsection of a permit | | `osha_case_summary` | OSHA case root | | `osha_citation` | Individual OSHA citation | | `narrative_window` | Fallback token-window chunk | ## Token-window fallback [#token-window-fallback] When a source has no identifiable structure (rare; mostly raw scraped HTML), Codex falls back to sliding-window chunking: * **Window:** 600 tokens * **Stride:** 550 tokens (50-token overlap) * **Chunk type:** `narrative_window` * **Section ID:** `"window.{seq_index}"` Overlap is zero for all structured chunks — duplication across chunks degrades retrieval precision. ## Parent-child retrieval [#parent-child-retrieval] You can use the chunk tree directly with parent-child retrieval frameworks like LangChain or LlamaIndex `ParentDocumentRetriever`: ```sql -- Retrieve a chunk's parent, then re-score at parent scope WITH hit AS ( SELECT chunk_id, doc_id, parent_chunk_id, chunk_text FROM codex.civic_intelligence_chunks WHERE chunk_id = :hit_chunk_id ) SELECT parent.chunk_text FROM hit JOIN codex.civic_intelligence_chunks parent ON parent.chunk_id = hit.parent_chunk_id; ``` ## Cross-encoder re-ranking [#cross-encoder-re-ranking] Initial retrieval over chunk embeddings is coarse. The recommended post-retrieval step is a cross-encoder re-rank over the top 50 results. Score pairs: `(query, chunk_text)`. Drop chunks below a `score_threshold` of 0.3. Codex does not run the re-ranker — this is a consumer-side pattern. The chunk structure (bounded size, clean boundaries) is designed to be compatible with standard re-ranking pipelines. ## Embedding policy [#embedding-policy] * **Default model:** `text-embedding-3-large` (OpenAI), 3072 dimensions, reduced to 1536 for storage. * **Re-embedding triggers:** model version bump or `chunking_version` bump. Embeddings are tagged with `embedding_model` and `embedding_version` so you can decide whether to re-embed. * **Deterministic re-embedding:** because `chunk_id` is deterministic, re-embedding the same text produces the same `chunk_id`. Embedding rows update in place without orphans. # Claim/fact separation (/codex/claim-fact-layer) For datasets where multiple sources may contradict each other — corporate ownership, permits, civic proceedings — Codex publishes records at two layers: **claims** (what sources asserted) and **facts** (Codex's resolution of those claims). This separation lets you trace every data point back to its origin and audit how contradictions were resolved. ## Why two layers [#why-two-layers] Collapsing contradictory source records into a single "truth row" breaks three use cases: 1. **Legal and compliance.** When two agencies disagree about a permit's effective date, you need to see both assertions and who made them — not whichever one a normalizer picked. 2. **CRE diligence.** When Assessor A says a parcel owner is X and Assessor B says Y, the answer is the distribution, not the pick. 3. **Regulated-AI workflows.** Downstream LLMs need to cite the source, not a Codex inference. Inferences belong to Codex; claims belong to the source. ## The two-layer model [#the-two-layer-model] * **Claims** are source-authored assertions, preserved verbatim with source attribution. Multiple claims per subject are expected and intentional. A claim never mutates after insert. * **Facts** are Codex-authored resolutions. A fact always cites its supporting claims via `supporting_claim_ids`. A fact can be superseded but never deleted — the reasoning trail is permanent. ## Claim schema [#claim-schema] Each claim captures what was asserted, where it can be verified, and who extracted it: ```json { "claim_id": "clm:urn:aprs:chunk:9f3a1b2c3d4e5f6a:entity.0", "subject": "urn:aprs:entity:person:k-johnson-phila", "predicate": "supports", "object": "urn:aprs:record:permit:phila:variance-2024-7b", "evidence_anchor": { "doc_id": "urn:aprs:record:civic:us:granicus:phila-2024-03-15-item7b", "page": 3, "char_span": [42, 118], "excerpt": "Councilmember Johnson: I support the variance as submitted..." }, "asserted_by": "civic_llm_extractor", "extractor_version": "civic_activation/0.9.1", "confidence": 0.91 } ``` ### Evidence anchor rules [#evidence-anchor-rules] * `doc_id` must be a valid APRS record URN reachable in a Codex dataset. * At least one of `page`, `char_span`, or `xpath` must be populated so you can verify the claim against the source. * `excerpt` (up to 400 characters) is populated when available for display convenience. ### Claim predicates [#claim-predicates] Claims use a controlled vocabulary of predicates. For Civic Intelligence v1: **Entity-to-record predicates:** `mentions`, `supports`, `opposes`, `abstains_on`, `introduces`, `represents_client_in`, `has_conflict_on` **Record-to-record predicates:** `supersedes`, `amends`, `cites`, `contradicts`, `continues_from` **Attribute predicates:** `has_status`, `has_value`, `has_effective_date` ## Fact schema [#fact-schema] Each fact records the resolution, its method, and which claims support it: ```json { "fact_id": "fct:urn:aprs:record:civic:us:granicus:phila-2024-03-15-item7b:upzoning_probability", "predicate": "upzoning_probability", "value": 0.82, "unit": "probability", "resolution_method": "llm_inference", "model_name": "distilbert-upzoning-v3", "model_version": "0.4.1", "supporting_claim_ids": [ "clm:urn:aprs:chunk:9f3a1b2c3d4e5f6a:entity.0", "clm:urn:aprs:chunk:9f3a1b2c3d4e5f6a:language_signal.2" ], "status": "current", "computed_at": "2024-03-19T05:03:22Z", "valid_from": "2024-03-15T00:00:00Z", "valid_to": null } ``` ### Resolution methods [#resolution-methods] Every fact carries a `resolution_method` explaining how Codex produced it: | Method | Description | | ------------------------ | --------------------------------------------------------------------------- | | `verbatim_single_claim` | Single source claim, passed through unchanged | | `authority_priority` | Multiple contradicting claims; higher-authority source wins | | `latest_by_published_at` | Most recent claim wins (typical for ownership, status fields) | | `majority_vote` | Three or more claims, simple majority (requires at least 2 agreeing) | | `weighted_vote` | Claims weighted by source reliability and confidence | | `llm_inference` | Downstream inference (e.g. `upzoning_probability`, `litigation_risk_score`) | | `manual_review` | Analyst-reviewed override | | `ensemble` | Weighted combination of multiple method outputs | ### Fact status [#fact-status] Facts transition through these states: | Status | Meaning | | -------------- | ------------------------------------------------------ | | `current` | The active resolution | | `superseded` | Replaced by a newer fact (new evidence arrived) | | `retracted` | Marked invalid by an analyst, with a documented reason | | `under_review` | Flagged for human review | A fact is never deleted. Consumers filtering for `status='current'` get the active view; querying all statuses gives the full history. ## Relationship to existing fields [#relationship-to-existing-fields] The claim/fact layer is **additive** — no existing fields are deprecated. Familiar fields like `entities_extracted`, `blockers`, and score fields remain in place as convenience views. | Existing field | In claim/fact model | | ----------------------- | ------------------------------------------------------------- | | `entities_extracted[]` | Each entity becomes one or more claims with entity predicates | | `blockers[]` | Each blocker tag becomes a claim with predicate `has_blocker` | | `language_signals[]` | Each signal becomes a claim with predicate `exhibits_signal` | | `upzoning_probability` | A fact with `resolution_method='llm_inference'` | | `hostility_index` | A fact with `resolution_method='llm_inference'` | | `litigation_risk_score` | A fact with `resolution_method='llm_inference'` | ## Export format [#export-format] Both layers ship as nested arrays on the parent record in Parquet exports and as sections in the Markdown-KV view. ### Parquet [#parquet] ```text civic_records ├── id, record_id, chunk_id, ... (APRS envelope) ├── entities_extracted[], blockers[], ... (convenience views) ├── claims: list> └── facts: list> ``` ### Markdown-KV [#markdown-kv] ```markdown ## Claims (3) - **clm:urn:...:entity.0** — {subject} `supports` {object} (conf 0.91) > "Councilmember Johnson: I support the variance as submitted..." ## Facts (2) - **fct:urn:...:upzoning_probability** = 0.82 - method: llm_inference (distilbert-upzoning-v3/0.4.1) - supports: clm:urn:...:entity.0, clm:urn:...:language_signal.2 - status: current ``` ## Example queries [#example-queries] ### All claims about a specific entity [#all-claims-about-a-specific-entity] ```sql SELECT r.id AS record_id, r.occurred_at, r.jurisdiction_slug, c->>'predicate' AS predicate, c->>'object' AS object, c->>'excerpt' AS excerpt FROM civic_records r, jsonb_array_elements(r.claims) AS c WHERE c->>'subject' = 'urn:aprs:entity:person:k-johnson-phila' ORDER BY r.occurred_at DESC; ``` ### Current upzoning probability with supporting claims [#current-upzoning-probability-with-supporting-claims] ```sql WITH f AS ( SELECT r.id, fact->>'value' AS prob, fact->'supporting_claim_ids' AS claim_ids FROM civic_records r, jsonb_array_elements(r.facts) AS fact WHERE r.id = :record_id AND fact->>'predicate' = 'upzoning_probability' AND fact->>'status' = 'current' ) SELECT f.prob, jsonb_agg(c) AS supporting_claims FROM f, civic_records r, jsonb_array_elements(r.claims) AS c WHERE r.id = f.id AND c->>'claim_id' = ANY (ARRAY(SELECT jsonb_array_elements_text(f.claim_ids))) GROUP BY f.prob; ``` ### Records where facts changed in the last 7 days [#records-where-facts-changed-in-the-last-7-days] ```sql SELECT r.id, r.jurisdiction_slug, COUNT(*) AS fact_revisions FROM civic_records r, jsonb_array_elements(r.facts) AS f WHERE (f->>'computed_at')::timestamptz > now() - interval '7 days' AND f->>'supersedes_fact_id' IS NOT NULL GROUP BY r.id, r.jurisdiction_slug ORDER BY fact_revisions DESC; ``` # Data catalog (/codex/data-catalog) Axiom Codex publishes eight datasets: Civic Intelligence, AIS Maritime Positions, Urban Signal Grid, Events Timeline, LEHD Commuter Flows, POI Intelligence, Permit Signals, and OSHA Safety Index. Every dataset follows the [normalization standard](/codex/normalization-standard), ships with pre-computed AI labels, and joins to any other Codex dataset without custom wrangling. ## Datasets [#datasets] **517K records** — Council votes, permits, and zoning decisions with entity extraction, sentiment scores, upzoning probability, and DAG-mapped approval sequences. Tags: NLP-ready, Labeled, Temporal Formats: Parquet, JSON Lines **1.4M positions** — Decoded vessel tracks, port calls, and anchor events enriched with Equasis vessel metadata, flag state, DWT, and kinematic fingerprints. Tags: Time-series, Enriched, Geospatial Formats: Parquet **454K H3 cells** — Cell-level ESGI composite scores and 8 signal-group subscores across 22 US metros at H3 resolution 8. Tags: Geospatial, Scored, Multi-signal Formats: GeoParquet, CSV **1.7M+ events** — Unified temporal intelligence spanning permits, council decisions, AIS anomalies, OSHA violations, and business openings normalized to a single event schema. Tags: Temporal, Multi-source, Cross-domain Formats: JSON Lines, Parquet **454K OD pairs** — Census LEHD worker origin-destination pairs normalized to H3 cells with income bands, job sector, and Huff gravity index pre-computed. Tags: Geospatial, Demographics, Transport Formats: CSV, Parquet **89K locations** — Points of interest enriched with category taxonomy, NAICS codes, pioneer business flags, walk/transit scores, and a reviews sample. Tags: Enriched, Categorized, Labeled Formats: JSON **2.1M permits** — Building permit activity across 22 metros with LLM-extracted scope type, building type, unit count, and estimated cost tier. Tags: NLP-extracted, Temporal, Development Formats: Parquet, CSV **500K+ inspections** — OSHA inspection records with NLP-classified hazard categories, violation severity tiers, and inflation-adjusted penalty normalization by H3 cell. Tags: NLP-classified, Safety, Industrial Formats: CSV, Parquet ## What makes Codex datasets different [#what-makes-codex-datasets-different] Every record in every dataset satisfies the [AI-Ready Public Record Standard (APRS)](/codex/normalization-standard). In practice, that means: * **Zero-wrangling joins.** A fixed set of [shared keys](/codex/join-keys) (`h3_index`, `event_id`, `jurisdiction_slug`, `mmsi`, `imo`, and more) lets you join any two datasets with a single SQL `JOIN`. * **Pre-computed AI labels.** Entity types, categories, sentiment, and risk scores are computed at normalization time — not at query time. * **LLM-ready formatting.** Every dataset ships a Markdown-KV view (`llm_text`) optimized for RAG and LLM reasoning, benchmarked at 60.7% accuracy versus 44.3% for raw CSV. * **Bitemporal timestamps.** Every record separates event time (`occurred_at`) from system time (`ingested_at`), publication time (`published_at`), and legal effective dates (`effective_from` / `effective_to`). * **Versioned monthly snapshots.** Immutable monthly releases you can pin to for reproducible research. * **Full provenance.** Every record carries a `provenance` chain documenting each transformation stage, and a `confidence_score` with per-dataset methodology. ## Pricing and delivery [#pricing-and-delivery] | Tier | Records | Formats | Price | | -------------- | -------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------- | | **Research** | 100K-record stratified sample | Parquet | Free on [Hugging Face](https://huggingface.co/axiom-ai) (CC-BY-4.0) | | **Commercial** | Full dataset | Parquet, CSV, JSON Lines, GeoParquet | $299/dataset/month | | **Enterprise** | Full dataset + [entity graph](/codex/entity-graph) | All formats + Markdown-KV | Contact sales | All paid tiers deliver monthly immutable Parquet snapshots via signed Cloudflare R2 download URLs. See [getting started](/codex/getting-started) for setup instructions. ## Standards compliance [#standards-compliance] Every dataset ships with a DCAT-US v3.0 `catalog.jsonld` sidecar for discoverability by data.gov-compatible crawlers. Per-dataset ontology crosswalks map Codex fields to the relevant domain standards: | Dataset | Target standards | | ---------------------- | ---------------------------------------------------- | | Civic Intelligence | DCAT-US v3.0, PROV-DM, schema.org/GovernmentService | | AIS Maritime Positions | IHO S-100, IMO A.600(15), ITU-R M.1371 | | Urban Signal Grid | OSCRE IDM 2.0, OGC API — Features, DCAT-US v3.0 | | Events Timeline | W3C PROV-DM, schema.org/Event, DCAT-US v3.0 | | LEHD Commuter Flows | Census TIGER/FIPS, OGC GeoJSON, DDI-Lifecycle | | POI Intelligence | schema.org/LocalBusiness, GS1 GLN, OGC GeoJSON | | Permit Signals | DCAT-US v3.0, schema.org/ConstructionPermit, PROV-DM | | OSHA Safety Index | schema.org/GovernmentPermit, NAICS, FRS, DCAT-US | Full crosswalks are available at [axiomcodex.io/standards](https://axiomcodex.io/standards). ## RAG and vector search [#rag-and-vector-search] Every dataset except AIS Maritime Positions ships with a `_chunks` Parquet file containing structure-aware chunks designed for retrieval-augmented generation. Chunks follow source boundaries (agenda items, speaker turns, permit scopes) rather than fixed token windows, and are compatible with LangChain and LlamaIndex `ParentDocumentRetriever` patterns. Each chunk carries: * A deterministic `chunk_id` (SHA-256-derived) for stable vector index keys * A `parent_chunk_id` for parent-child retrieval * An `evidence_anchor` for tracing back to the source document * Token counts and embedding metadata AIS Maritime Positions are point-in-time records and are not chunked. The Urban Signal Grid, LEHD Commuter Flows, and POI Intelligence datasets use their compact Markdown-KV views as single-record chunks. ## Next steps [#next-steps] The contract every record satisfies — field definitions, versioning rules, and conformance requirements. The registry of shared keys that make cross-dataset joins work without wrangling. How records are chunked for RAG — structure-aware boundaries, deterministic IDs, and parent-child retrieval. A Parquet edge-list for multi-hop reasoning over entities, vessels, permits, and jurisdictions (Enterprise tier). Per-dataset reference for every temporal field, so you always know which clock a timestamp is on. How source assertions are separated from resolved facts, with full provenance. Jupyter notebooks demonstrating upzoning classification and civic risk mapping with research-tier data. # Entity graph export (/codex/entity-graph) Vector search alone fails on multi-hop reasoning — corporate ownership chains, compliance lineage, cascading civic approvals, vessel-to-company-to-sanction chains. The entity graph export gives you a compact, queryable edge list you can import into your own graph layer. The entity graph export is available on the **Enterprise tier** only. It ships as `codex_entity_graph.parquet` alongside per-dataset slices and a stats sidecar with every Enterprise catalog purchase. ## What you get [#what-you-get] A single Parquet edge-list file (Snappy-compressed) with per-dataset slices. This is not a graph database — you import it into your own graph engine (Neo4j, Kuzu, TigerGraph, DuckDB, NetworkX, or similar). Expected size at launch: approximately 8–12 million edges across all dataset families. ## Edge schema [#edge-schema] Each edge in the graph has the following fields: | Field | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------- | | `from_id` | string | APRS URN or raw ID (e.g. H3 index, MMSI) | | `from_type` | string | Node type of the source (see [node types](#node-types)) | | `edge_type` | string | Relationship type (see [edge types](#edge-types)) | | `to_id` | string | APRS URN or raw ID | | `to_type` | string | Node type of the target | | `confidence` | float | Pipeline confidence in the edge, 0 to 1 | | `source_dataset` | string | Which Codex dataset emitted it | | `source_record_id` | string | Record that generated the edge (for provenance) | | `valid_from` | date | When the relationship became true | | `valid_to` | date | When it stopped being true (null = currently valid) | | `extracted_at` | timestamp | When the pipeline extracted the edge | | `extractor` | string | Name and version of the extractor | | `evidence_anchor` | JSON | `{doc_id, page, span}` where applicable | | `attrs` | JSON | Edge-type-specific metadata (e.g. vote tally, ownership percentage) | ## Node types [#node-types] Every node is addressable by a stable ID. Most use [APRS URNs](/codex/join-keys). | Node type | ID format | Source | | --------------------- | ---------------------------------------- | -------------------------------------- | | `entity:person` | `urn:aprs:entity:person:{id}` | Civic records, OSHA, entity resolution | | `entity:organization` | `urn:aprs:entity:company:{id}` | Government records, permits | | `entity:agency` | `urn:aprs:entity:agency:{id}` | Issuing authorities | | `entity:vessel` | `urn:aprs:record:maritime:vessel:{imo}` | AIS and Equasis | | `entity:trust` | `urn:aprs:entity:trust:{id}` | Beneficial ownership resolution | | `record:civic` | `urn:aprs:record:civic:us:{source}:{id}` | Civic Intelligence | | `record:permit` | `urn:aprs:record:permit:...` | Permit Signals | | `record:event` | `urn:axiom:event:{uuid}` | Events Timeline | | `record:osha_case` | `urn:aprs:record:osha:case:{id}` | OSHA Safety | | `record:poi` | `urn:aprs:record:poi:{source}:{id}` | POI Intelligence | | `record:parcel` | `{jurisdiction_slug}:{parcel-number}` | Permits, assessor feeds | | `h3_cell` | Raw H3 res-8 string | Derived across datasets | | `port` | `urn:axiom:port:{unlocode}` | AIS Maritime | | `jurisdiction` | `jurisdiction_slug` | Civic, Permits | ## Edge types [#edge-types] ### Civic [#civic] | Edge type | Direction | Attributes | | ----------------- | ----------------------------------- | -------------------------------------- | | `SUPPORTS` | entity:person → record:civic | `mention_count`, `excerpt_span` | | `OPPOSES` | entity:person → record:civic | `mention_count`, `excerpt_span` | | `ABSTAINS_ON` | entity:person → record:civic | `mention_count`, `excerpt_span` | | `MENTIONS` | record:civic → entity | `sentiment`, `role`, `mention_count` | | `REPRESENTS` | entity:person → entity:organization | `capacity` (attorney, lobbyist, staff) | | `HAS_CONFLICT_ON` | entity:person → record:civic | `source` | | `AMENDS` | record:civic → record:civic | `relationship_type` | ### Events [#events] | Edge type | Direction | Attributes | | ----------- | --------------------------- | ------------------------------------------ | | `FOLLOWS` | record:event → record:event | `lag_days` | | `TRIGGERED` | record:event → record:event | Reverse of `FOLLOWS` for cascade detection | | `AFFECTS` | record:event → entity | When event has an `entity_id` | | `OCCURS_AT` | record:event → h3\_cell | Spatial index | ### Maritime [#maritime] | Edge type | Direction | Attributes | | --------------- | ----------------------------------- | ------------------------------------------- | | `CALLED_AT` | entity:vessel → port | `eta`, `ata`, `etd`, `atd`, `berth_id` | | `OWNS` | entity:organization → entity:vessel | `ownership_pct`, `effective_from`, `source` | | `MANAGES` | entity:organization → entity:vessel | `source` | | `FLAGS` | entity:vessel → jurisdiction | `flag_state_iso3` | | `SANCTIONED_BY` | entity:organization → jurisdiction | `sanctions_list`, `listed_on` | ### Permits [#permits] | Edge type | Direction | Attributes | | --------------- | --------------------------------------------- | -------------------- | | `LOCATED_IN` | record:permit → h3\_cell | Direct H3 mapping | | `LOCATED_ON` | record:permit → record:parcel | When parcel is known | | `APPLIED_BY` | record:permit → entity | Applicant | | `ISSUED_BY` | record:permit → entity:agency | Authority | | `CONTINGENT_ON` | record:permit → record:permit or record:civic | Scope dependency | ### Urban Signal Grid [#urban-signal-grid] | Edge type | Direction | Attributes | | ----------- | -------------------------------------- | ------------------------------ | | `HAS_SCORE` | h3\_cell → score node | `composite_score`, `scored_at` | | `CONTAINS` | h3\_cell → record:poi or record:permit | Spatial join | | `NEIGHBORS` | h3\_cell → h3\_cell | `k: 1` (direct neighbor only) | ### OSHA [#osha] | Edge type | Direction | Attributes | | ------------------ | ----------------------------------------- | ------------------------------- | | `ENFORCED_AGAINST` | record:osha\_case → entity:organization | `penalty_usd`, `citation_count` | | `PARENT_OF` | entity:organization → entity:organization | Corporate parent links | | `AT_FACILITY` | record:osha\_case → record:poi | When FRS match exists | ## Example queries [#example-queries] You can query the graph directly with DuckDB and Parquet — no external graph database required. ### Vessel → owner → sanctions → sister vessels [#vessel--owner--sanctions--sister-vessels] ```sql WITH owners AS ( SELECT from_id AS owner_id FROM codex.entity_graph WHERE edge_type = 'OWNS' AND to_id = :vessel_urn ), sanctioned AS ( SELECT from_id AS owner_id FROM codex.entity_graph WHERE edge_type = 'SANCTIONED_BY' AND from_id IN (SELECT owner_id FROM owners) ), other_vessels AS ( SELECT to_id AS sister_vessel FROM codex.entity_graph WHERE edge_type = 'OWNS' AND from_id IN (SELECT owner_id FROM sanctioned) AND to_id != :vessel_urn ) SELECT * FROM other_vessels; ``` ### Recursive cascade — downstream records from a dark event (up to 3 hops) [#recursive-cascade--downstream-records-from-a-dark-event-up-to-3-hops] ```sql WITH RECURSIVE reachable(id, hop) AS ( SELECT :seed_event_uuid, 0 UNION ALL SELECT e.to_id, r.hop + 1 FROM codex.entity_graph e JOIN reachable r ON e.from_id = r.id WHERE e.edge_type IN ('FOLLOWS', 'TRIGGERED', 'AFFECTS') AND r.hop < 3 ) SELECT r.id, r.hop, e.to_type FROM reachable r JOIN codex.entity_graph e ON e.from_id = r.id; ``` ## Provenance [#provenance] Every emitted edge carries `evidence_anchor`, `extractor`, and `confidence`, following the same contract as the [claim/fact layer](/codex/claim-fact-layer). You can join edges on `source_record_id` back to the record's `claims[]` array for full provenance. ## Tier availability [#tier-availability] | Tier | Graph export included | | ---------- | :-----------------------------------------------------: | | Research | No | | Commercial | No | | Enterprise | Yes — full graph, per-dataset slices, and stats sidecar | # Envelope coverage dashboard (/codex/envelope-coverage) The envelope coverage dashboard shows how far along each catalog table is in adopting the [APRS data envelope](/locus/data-standards). Open it at **Admin → Codex coverage** (`/admin/codex-coverage`) to see, at a glance, which tables are fully compliant, which are in progress, and which haven't started yet. ## Why it matters [#why-it-matters] Every row in the Codex catalog needs a populated `record_id` to be traceable, deduplicated, and exportable in [audit packages](/codex/audit-export). The coverage dashboard gives you a single view into that progress so you can answer questions like: * How close is my dataset to full APRS compliance? * Which tables still have unpopulated records? * Are nightly backfill jobs actually making progress? ## What you'll see [#what-youll-see] ### Summary cards [#summary-cards] At the top of the dashboard, four summary cards show: | Card | Description | | ------------------- | ---------------------------------------------------------------- | | **Tables tracked** | Total number of catalog tables with a `record_id` column. | | **Fully compliant** | Tables where ≥ 99% of rows have a populated `record_id`. | | **Empty / 0%** | Tables where no rows have been backfilled yet. | | **In progress** | Everything in between — backfill has started but isn't complete. | An overall percentage is displayed alongside the total number of envelope-compliant rows out of all rows across every tracked table. ### Coverage table [#coverage-table] Below the summary cards, a sortable table lists every catalog table, ordered worst-first by default. Each row shows: | Column | Description | | ----------------- | -------------------------------------------------------------------------------------- | | **Table** | The catalog table name and its source key (if available). | | **Category** | The data category the table belongs to. | | **Rows** | Total row count in the table. | | **Populated** | Number of rows with a populated `record_id`. | | **%** | Percentage of rows that are envelope-compliant, color-coded by bucket. | | **Last backfill** | When the most recent backfill job ran for this table, plus how many rows it processed. | ### Color-coded status buckets [#color-coded-status-buckets] The percentage column is color-coded so you can scan for problem areas quickly: | Color | Range | Meaning | | ----- | ------- | ------------------------------------------------------------- | | Gray | 0% | No rows backfilled yet. | | Red | \< 25% | Early stages — backfill has started but has a long way to go. | | Amber | 25%–74% | In progress — backfill is underway. | | Blue | 75%–98% | Almost there — most rows are compliant. | | Green | ≥ 99% | Fully compliant. | ## How data refreshes [#how-data-refreshes] Coverage statistics are refreshed automatically by a nightly job that runs at **05:00 UTC**, after the backfill window finishes. The dashboard header shows when the last refresh occurred. You don't need to trigger refreshes manually. Each nightly run scans every catalog table that has a `record_id` column, counts total rows versus populated rows, and updates the dashboard. If a table was recently added to the catalog, it will appear on the dashboard after the next nightly refresh. ## Compliance views [#compliance-views] Two SQL views give you direct access to coverage and backfill data without leaving your database client. Use them for ad-hoc queries, alerting integrations, or any workflow where you need the raw numbers behind the dashboard. ### `codex_compliance_summary` [#codex_compliance_summary] Returns one row per tracked table with coverage percentages for every [APRS envelope](/locus/data-standards) column, plus `h3_index` and `mmsi`. Coverage is derived from PostgreSQL catalog statistics (`pg_stats.null_frac`), so the query is fast and doesn't scan table data. ```sql select * from codex_compliance_summary; ``` | Column | Description | | -------------------- | ---------------------------------------------------------- | | `table_name` | The catalog table (e.g. `ais_positions`, `vessel_visits`). | | `table_size` | Human-readable table size on disk. | | `record_id_pct` | Percentage of rows with a populated `record_id`. | | `source_uri_pct` | Percentage of rows with a populated `source_uri`. | | `source_system_pct` | Percentage of rows with a populated `source_system`. | | `chunk_id_pct` | Percentage of rows with a populated `chunk_id`. | | `occurred_at_pct` | Percentage of rows with a populated `occurred_at`. | | `h3_index_pct` | Percentage of rows with a populated `h3_index`. | | `mmsi_pct` | Percentage of rows with a populated `mmsi`. | | `stats_refreshed_at` | When PostgreSQL last ran `ANALYZE` on the table. | Coverage percentages are based on the most recent `ANALYZE` run. If you need sub-percentage-point accuracy, run `ANALYZE` on the target table first: ```sql analyze ais_positions; select * from codex_compliance_summary where table_name = 'ais_positions'; ``` ### `codex_backfill_progress` [#codex_backfill_progress] Shows the status of `h3_index` and `mmsi` backfill jobs over the last seven days. Each row represents one table with aggregated run counts, rows updated, and a stall indicator. ```sql select * from codex_backfill_progress; ``` | Column | Description | | -------------------- | ----------------------------------------------------------------------- | | `table_name` | The table being backfilled. | | `run_count` | Number of backfill runs in the last seven days. | | `total_rows_updated` | Total rows updated across all runs. | | `last_run_at` | Timestamp of the most recent completed run. | | `since_last_run` | Interval since the last run (useful for spotting gaps). | | `last_cursor` | The cursor position where the last run stopped. | | `status` | `running` if the last run was within five minutes, `stalled` otherwise. | Use this view to detect stuck backfills before they fall behind: ```sql select table_name, status, since_last_run from codex_backfill_progress where status = 'stalled'; ``` ## Vessel-level coverage for port events [#vessel-level-coverage-for-port-events] The `port_events` table now includes a dedicated `mmsi` column, completing the full APRS envelope for port-level activity data. This means you can: * **Join port events to vessel records** — link arrivals, departures, and berth assignments directly to a vessel's MMSI without going through a separate lookup table. * **Run spoofing-detection queries** — the `mmsi` column is indexed (partial index on non-null values), so queries that cross-reference vessel identity against port activity are fast even at scale. * **Track `mmsi` coverage in the dashboard** — the `codex_compliance_summary` view reports `mmsi_pct` for every tracked table, including `port_events`. ```sql -- Find port events for a specific vessel select * from port_events where mmsi = '211331640' order by occurred_at desc limit 20; ``` ## CLI compliance checker [#cli-compliance-checker] The `codex.cli check` command validates APRS envelope compliance for any table -- or all tables at once -- from the command line. It samples recent rows and runs nine validation checks covering identity, provenance, temporal ordering, and access-tier fields. ### Running a check [#running-a-check] Check a single table: ```bash python -m groundswell_collector.codex.cli check civic_records ``` Check all tables and write a JSON report: ```bash python -m groundswell_collector.codex.cli check all --limit 500 --report /tmp/aprs.json ``` | Flag | Default | Description | | ---------- | ------- | ----------------------------------------------- | | `--limit` | 1000 | Number of most-recent rows to sample per table. | | `--report` | — | Path to write a JSON report file. | ### What gets checked [#what-gets-checked] Each sampled row is validated against nine checks: | Check | Severity | Rule | | ----------------------- | -------- | -------------------------------------------------- | | `record_id` | critical | Must be a valid APRS URN (`urn:aprs:record:...`). | | `source_uri` | critical | Must be non-null. | | `ingested_at` | critical | Must be valid ISO 8601. | | `schema_version` | critical | Must match `aprs.{domain}/{semver}`. | | `normalization_version` | warning | Must be semver. | | `occurred_at` | warning | Should be set when semantically applicable. | | `temporal_order` | critical | `occurred_at` must not be after `ingested_at`. | | `effective_order` | critical | `effective_from` must not be after `effective_to`. | | `acl_tier` | warning | Must be `research`, `commercial`, or `internal`. | ### Per-table column introspection [#per-table-column-introspection] The compliance checker dynamically discovers which envelope columns each table actually has before running checks. This means: * Tables that use a timestamp column other than `created_at` for ordering (such as `timestamp` on AIS positions, `started_at` on events, `loaded_at` on building permits, or `updated_at` on vessels) are handled correctly. * Optional envelope fields like `occurred_at`, `effective_from`, and `effective_to` are only validated if the table has those columns. A missing optional column is not treated as non-compliant. * The checker exits non-zero if any table has critical issues affecting more than 5% of sampled rows, making it suitable for CI pipelines. The compliance checker runs automatically in CI on every pull request that touches data collectors or migrations. You can also run it locally to validate your changes before pushing. ### Reading the output [#reading-the-output] The checker prints a formatted report with pass, warning, and fail indicators for each table: * **Pass** — all critical checks above 95% compliance. * **Warning** — non-critical checks below threshold, but no critical failures. * **Fail** — one or more critical checks below 95% compliance. The optional `--report` JSON file includes per-table compliance rates and individual issue details, suitable for dashboards or alerting integrations. ## When to use it [#when-to-use-it] * **During APRS rollout** — monitor adoption as backfill jobs work through historical data. Commodity tables (`conab_crop_reports`, `antt_road_freight`, `cepea_commodity_prices`) and maritime tables (`antaq_vessel_calls`, `usace_lock_passages`) now populate envelope fields at write time, so new rows appear as compliant immediately. * **Before an audit** — confirm that all evidence tables are fully envelope-compliant before generating an [audit export](/codex/audit-export). * **Troubleshooting stalled backfills** — if a table's percentage hasn't changed in several days and the "Last backfill" timestamp is stale, the backfill job for that table may need attention. Query `codex_backfill_progress` to check whether the job is `running` or `stalled`. * **Programmatic alerting** — query `codex_compliance_summary` or `codex_backfill_progress` from your monitoring tools to trigger alerts when coverage drops or backfills stall. # FedRAMP (/codex/fedramp) FedRAMP (Federal Risk and Authorization Management Program) is the federal government's authorization regime for cloud services. Any SaaS sold to a federal agency needs a FedRAMP authorization at the appropriate impact level. This is the most expensive compliance program your company will encounter — but also the highest-value, because it gates a customer base that often pays 2-5x commercial pricing. ## Impact levels [#impact-levels] | Level | Data sensitivity | Customer examples | | ------------------------------ | ------------------------------- | -------------------------------------------------------------- | | **FedRAMP Tailored (LI-SaaS)** | Public, low-impact | Public-facing form apps, simple data collection | | **FedRAMP Low** | Public business data | Marketing analytics, public-portal CMS | | **FedRAMP Moderate** | Sensitive but unclassified data | Most B2B SaaS — CRM, project management, HR, financial systems | | **FedRAMP High** | Mission-critical, life-safety | DoD, intelligence community, IRS-data-handling systems | **\~80% of federal SaaS authorizations are Moderate.** Plan for that as your target unless you have specific intel/DoD customers. ## Costs and timeline [#costs-and-timeline] | Path | Timeline | Total cost (3PAO + remediation + internal) | | -------------------- | ------------ | ------------------------------------------ | | **FedRAMP Tailored** | 6-9 months | $50K-150K | | **FedRAMP Low** | 9-12 months | $150K-300K | | **FedRAMP Moderate** | 12-18 months | $300K-700K | | **FedRAMP High** | 18-24 months | $500K-1M+ | Add 6-12 months for the federal customer's Authorization to Operate (ATO) review on top of the FedRAMP authorization itself. ## Authorization paths [#authorization-paths] **Agency ATO** — sponsored by a specific federal agency. The agency reviews your package, issues an ATO, and you're authorized for that agency. **JAB P-ATO** — Joint Authorization Board provisional ATO. Reviewed centrally by FedRAMP PMO, accepted across all federal agencies. Higher bar; longer timeline. JAB has limited slots per year. **Most companies start with Agency ATO** — find a sponsoring agency (often via a contractor relationship), get authorized, then optionally pursue JAB later for broader market access. ## Required infrastructure decisions [#required-infrastructure-decisions] Before pursuing FedRAMP, two infrastructure choices have to be made — both expensive to reverse: ### 1. Cloud service provider [#1-cloud-service-provider] You can only run on a FedRAMP-authorized CSP. The big options: * **AWS GovCloud** — Moderate and High authorized; widely used for FedRAMP workloads * **Azure Government** — Moderate and High authorized; Microsoft's federal offering * **GCP Assured Workloads (FedRAMP)** — Moderate authorized; smaller federal footprint * **Oracle Cloud for Government** — Moderate; less common for SaaS Your application has to run on one of these — not commercial AWS. This typically means a separate deployment + separate codebase fork (or compile flags). ### 2. Data residency [#2-data-residency] FedRAMP requires data stay in US territory, processed by US persons. This means: * **No offshore engineering for FedRAMP customers** — your federal deployment can't be touched by non-US engineers * **No SaaS dependencies that aren't FedRAMP-authorized themselves** — every CSP, every analytics tool, every monitoring service must be FedRAMP-authorized too Inventory your dependencies BEFORE committing to FedRAMP. The SaaS-supply-chain audit is brutal. ## How Codex maps the FedRAMP Moderate baseline [#how-codex-maps-the-fedramp-moderate-baseline] FedRAMP Moderate is essentially **NIST 800-53 Moderate baseline + \~25 FedRAMP-specific control parameters + continuous monitoring**. The control catalog is the same as the [NIST 800-53 guide](/codex/nist-800-53). FedRAMP-specific additions: ### Continuous monitoring (ConMon) [#continuous-monitoring-conmon] Federal customers expect monthly evidence of ongoing security. Codex generates the monthly ConMon report: * **Vulnerability scan results** — monthly + remediation SLA tracking (Critical: 30d, High: 30d, Moderate: 90d, Low: 180d) * **Plan of Action and Milestones (POAM)** updates — open issues + target close dates * **System inventory changes** — hardware/software added or removed * **User access changes** — provisioned, modified, terminated since last report * **Configuration changes** — CM-3 compliant baseline drift report ### FedRAMP-specific control enhancements [#fedramp-specific-control-enhancements] A few controls have FedRAMP-mandated parameters tighter than 800-53 baseline: | Control | FedRAMP requirement | | ------------------------------------- | -------------------------------------------------------------- | | **AC-2(7)** Account Management | Privileged accounts reviewed monthly (vs annually in baseline) | | **AU-6** Audit Review | Logs reviewed weekly (vs as-needed in baseline) | | **CM-3** Configuration Change Control | Major changes require formal CCB approval | | **IR-3** Incident Response Testing | Annual tabletop exercise with documented results | | **RA-5** Vulnerability Scanning | Monthly authenticated + unauthenticated scans by an ASV | ### FIPS-validated cryptography [#fips-validated-cryptography] Every encryption operation in scope must use FIPS 140-2 (or 140-3) validated cryptographic modules. Most cloud-native crypto (AWS KMS, Azure Key Vault, GCP Cloud KMS) is FIPS-validated, but you must explicitly enable FIPS mode on operating systems and verify your application code calls FIPS-mode crypto libraries. Codex tracks FIPS-mode status per system. ## The 3PAO and assessment [#the-3pao-and-assessment] You hire a Third-Party Assessment Organization (3PAO) — a FedRAMP-accredited audit firm — to conduct the formal assessment. They review your System Security Plan (SSP), test controls in your environment, and produce a Security Assessment Report (SAR). 3PAO fees alone: **$150K-400K** depending on scope and complexity. Codex evidence packages reduce 3PAO time significantly (anecdotally, 30-40%) by giving them clean, timestamped evidence rather than ad-hoc spreadsheets — but it doesn't eliminate the engagement. ## When you're ready [#when-youre-ready] **Reports → FedRAMP evidence package** outputs: * SSP supporting evidence (per-control implementation evidence) * Continuous monitoring report (monthly format) * POAM with current status * Boundary diagram + data flow diagram (you draw these; Codex tracks the underlying inventory) * Authority list (named control owners + responsibility matrix) * 3PAO-friendly export format (designed to drop into the standard FedRAMP templates) For agencies you've already authorized with, monthly ConMon reports submit directly into the federal customer's portal. For new agency ATOs, your sponsoring agency reviews this package alongside the 3PAO SAR. # Get started with Codex (/codex/getting-started) Axiom Codex ships eight normalized datasets as monthly Parquet snapshots: Civic Intelligence, AIS Maritime Positions, Urban Signal Grid, Events Timeline, LEHD Commuter Flows, POI Intelligence, Permit Signals, and OSHA Safety Index. Every record follows the [APRS standard](/codex/normalization-standard), carries pre-computed AI labels, and joins to any other Codex dataset via [shared keys](/codex/join-keys). Pick a tier below, grab a dataset, and run your first query.

Axiom Codex entity graph showing a selected vessel entity connected to companies, ports, voyages, events, and documents, alongside its canonical attributes

## Choose your tier [#choose-your-tier] | | Research | Commercial | Enterprise | | ---------------- | ------------------------------------------------------- | ------------------------------------ | -------------------------------------------------- | | **Access** | Free on [Hugging Face](https://huggingface.co/axiom-ai) | Signed R2 download URL | Signed R2 download URL | | **Records** | 100K-record stratified sample per dataset | Full dataset | Full dataset | | **Formats** | Parquet | Parquet, CSV, JSON Lines, GeoParquet | All formats + Markdown-KV | | **Snapshots** | Latest only | Monthly immutable snapshots | Monthly immutable snapshots | | **Entity graph** | — | — | Full graph export ([details](/codex/entity-graph)) | | **License** | CC-BY-4.0 (attribution required) | Commercial license, per dataset | Commercial license, all datasets | | **Price** | Free | $299/dataset/month | Contact sales | Start with the Research tier to explore schema, field coverage, and join keys before committing to a commercial license. ## Download a dataset [#download-a-dataset] ### Research tier — Hugging Face [#research-tier--hugging-face] Browse the [Axiom AI organization on Hugging Face](https://huggingface.co/axiom-ai) and download any dataset directly. Each dataset includes a README with schema documentation and a 100K-record stratified sample in Parquet format. ### Commercial or Enterprise tier [#commercial-or-enterprise-tier] Purchase a license at [axiomcodex.io](https://axiomcodex.io). After checkout, your license key and signed download URL are emailed to the address used at checkout — delivery normally lands within a minute. The URL points to a monthly Parquet snapshot on Cloudflare R2. If the email doesn't arrive, your license key is also stored on the subscription itself in Stripe. Use the **Manage subscription** link in the original receipt to open the Stripe customer portal and surface the key, or contact [support@axiomancer.io](mailto:support@axiomancer.io) and we'll resend. ## Run your first query [#run-your-first-query] Load any Codex Parquet file into DuckDB, Pandas, Spark, or your preferred tool. Every dataset uses the same [APRS envelope](/codex/normalization-standard), so once you learn one, you know them all. ### DuckDB [#duckdb] ```sql SELECT record_id, occurred_at, jurisdiction_slug, event_type FROM read_parquet('civic-intelligence-2026-04.parquet') WHERE jurisdiction_slug = 'philadelphia-pa' AND occurred_at >= '2026-01-01' LIMIT 20; ``` ### Python (Pandas) [#python-pandas] ```python import pandas as pd df = pd.read_parquet("civic-intelligence-2026-04.parquet") phila = df[df["jurisdiction_slug"] == "philadelphia-pa"] print(phila[["record_id", "occurred_at", "event_type"]].head(20)) ``` ## Join two datasets [#join-two-datasets] Every Codex dataset shares a common set of [join keys](/codex/join-keys). Join Civic Intelligence to Urban Signal Grid via `h3_index` without any wrangling: ```sql SELECT cells.h3_index, cells.composite_score, civic.event_type, civic.occurred_at FROM read_parquet('urban-signal-grid-2026-04.parquet') cells JOIN read_parquet('civic-intelligence-2026-04.parquet') civic USING (h3_index) WHERE civic.event_type = 'zoning_vote' AND cells.composite_score > 0.7; ``` ## Use the LLM-ready surface [#use-the-llm-ready-surface] Every dataset ships a `llm_text` column in Markdown-KV format, optimized for RAG pipelines and LLM reasoning. Feed it directly into your retrieval system or prompt: ```markdown - chunk_id: urn:aprs:chunk:9f3a1b2c... - record_id: urn:aprs:record:civic:us:granicus:phila-2024-03-15-item7b - jurisdiction: Philadelphia, PA - occurred_at: 2024-03-15 - event_type: zoning_vote - summary: Council voted 11-6 to approve rezoning of the 2200 block... - entities: {name: Kenyatta Johnson, role: councilmember, sentiment: supportive} - litigation_risk_score: 0.42 ``` Pre-computed [chunks](/codex/chunking-policy) are available in a companion `_chunks` Parquet file for each dataset, ready for vector indexing. ## Next steps [#next-steps] Browse all eight datasets with record counts, formats, and tags. The APRS contract every record satisfies — field definitions, versioning, and conformance. The registry of shared keys that make cross-dataset joins work. Per-dataset reference for every temporal field, so you always know which clock a timestamp is on. # HIPAA evidence catalog (/codex/hipaa-evidence-catalog) HIPAA Security Rule has 18 standards across Administrative, Physical, and Technical safeguards. This page lists the per-standard evidence Codex collects for SaaS Business Associates. Companion to the [HIPAA framework guide](/codex/hipaa). ## Administrative safeguards (§ 164.308) [#administrative-safeguards--164308] ### § 164.308(a)(1) — Security management process [#-164308a1--security-management-process] Required evidence: * **Risk analysis** — annual risk assessment document with sign-off * **Risk management** — remediation tracking from your ticketing system (PagerDuty, Linear, Jira) * **Sanction policy** — link to published HR policy + acknowledgment records * **Information system activity review** — log review records (who reviewed, when, finding count) Codex tracks the cadence + completion of each. ### § 164.308(a)(3) — Workforce security [#-164308a3--workforce-security] ```text User: alice@company.com Hire date: 2026-01-15 Authorization: granted by carol@company.com (manager) Access provisioned: 2026-01-15 09:00 (Okta + Google Workspace) Background check: completed 2026-01-10 (Checkr, status: clear) Termination: not applicable (active) ``` Per-user authorization chain pulled from HRIS + IdP + ticketing system. ### § 164.308(a)(4) — Information access management [#-164308a4--information-access-management] Per-user, per-system access table with last-review timestamp. Filtered to PHI-handling systems. ```text User: alice@company.com Access to: - EHR system (Epic) role: clinical user reviewed: 2026-04-01 - Patient data export tool role: read-only reviewed: 2026-04-01 - Medication ordering role: not granted reviewed: 2026-04-01 ``` ### § 164.308(a)(5) — Security awareness and training [#-164308a5--security-awareness-and-training] LMS connector pulls per-user training completion for HIPAA-specific courses: * HIPAA basics (annual) * Phishing awareness (quarterly) * Role-specific training (e.g. clinical staff get PHI handling specifics) Codex flags any active user without current training as an exception. ### § 164.308(a)(6) — Security incident procedures [#-164308a6--security-incident-procedures] Per-incident evidence with PHI-specific attributes: * Was PHI involved? (yes/no/unknown — categorization required by Breach Notification Rule) * Number of records affected (if PHI) * Detection time, containment time, notification time * Notification recipients (Covered Entity, HHS if breach > 500 records, affected individuals) ### § 164.308(a)(7) — Contingency plan [#-164308a7--contingency-plan] | Sub-standard | Evidence | | ------------------------------------------ | ------------------------------------------------------------------------------------- | | Data backup plan | Backup snapshot history per PHI-handling system | | Disaster recovery plan | Linked DR runbook + last review timestamp | | Emergency mode operation plan | Documented degraded-mode procedures + test results | | Testing and revision procedures | Quarterly DR test results (you upload, Codex stores with timestamp + tester identity) | | Applications and data criticality analysis | Documented inventory of PHI systems by criticality tier | ### § 164.308(a)(8) — Evaluation [#-164308a8--evaluation] Codex itself is the evaluation tool — quarterly evidence package shows ongoing review of all controls. ## Physical safeguards (§ 164.310) [#physical-safeguards--164310] ### § 164.310(a) — Facility access controls [#-164310a--facility-access-controls] For SaaS-only Business Associates: * Office walk-through checklist (semi-annual; you upload) * Visitor log review (if you receive PHI couriers) * Server-room access for any on-prem infrastructure (most BAs run cloud-only — N/A with documented justification) ### § 164.310(b) — Workstation use [#-164310b--workstation-use] MDM device inventory filtered to "PHI-handling devices" (you tag which devices in MDM): * Approved use policy acknowledged per user * Device location restrictions (e.g. "no PHI work from public WiFi") ### § 164.310(c) — Workstation security [#-164310c--workstation-security] | Control | MDM evidence | | --------------------------- | ------------------------------------------------------- | | Screen lock policy | Per-device idle timeout + auto-lock enforcement | | Encryption | FileVault (Mac), BitLocker (Windows), per-device status | | Approved software inventory | Application allowlist enforcement | ### § 164.310(d) — Device and media controls [#-164310d--device-and-media-controls] Per-device lifecycle evidence: * Provisioning (when, to whom, configuration applied) * Reassignment events (with secure-wipe attestation) * Decommission (secure-wipe certificate + disposal method) For removable media: usage logs + encryption-at-rest enforcement (BitLocker To Go, FileVault USB). ## Technical safeguards (§ 164.312) [#technical-safeguards--164312] ### § 164.312(a) — Access control [#-164312a--access-control] Codex builds the four required components: | Component | Evidence | | -------------------------- | ------------------------------------------------------------ | | Unique user identification | IdP user inventory — every account has a unique identifier | | Emergency access procedure | Documented break-glass procedure + audit log of activations | | Automatic logoff | MDM screen lock + app-level session timeout configuration | | Encryption and decryption | At-rest encryption status per PHI store + KMS key management | ### § 164.312(b) — Audit controls [#-164312b--audit-controls] SIEM event coverage per PHI-handling system: * All access events logged (read, write, query, export) * Logs retained for 6 years (HIPAA minimum) * Log integrity controls (CloudTrail / Activity Log immutability) * Log review records (who reviewed, when, anomaly count) ### § 164.312(c) — Integrity [#-164312c--integrity] For PHI in transit + at rest: * Database integrity constraints (foreign keys, checksums) * File-integrity monitoring on PHI stores (cloud connector audit reports) * Cryptographic verification of backup restores ### § 164.312(d) — Person or entity authentication [#-164312d--person-or-entity-authentication] Per-user authentication strength report: * MFA enrolled (Y/N, factor types) * Conditional access policies applied * Failed authentication events (correlation to alerts) ### § 164.312(e) — Transmission security [#-164312e--transmission-security] | Channel | Evidence | | ----------------- | ----------------------------------------------- | | HTTPS endpoints | TLS coverage scan (TLS 1.2+, no weak ciphers) | | Email transport | SMTP TLS enforcement + DMARC/DKIM/SPF config | | Internal services | Service-mesh mTLS configuration | | File transfer | SFTP-only, no FTP; key-based auth, no passwords | ## Business Associate Agreements [#business-associate-agreements] Tracked separately under [BAA workflow](/codex/baa-workflow). Audit-package export includes the current BAA inventory snapshot + outstanding gaps. ## What this catalog isn't [#what-this-catalog-isnt] HIPAA Security Rule is one of two rule sets that apply to Business Associates. The Privacy Rule (handling, disclosure, patient rights) is mostly process-based and tracked via document links + attestations rather than auto-evidenced API calls. See the [HIPAA framework guide](/codex/hipaa) for the full mapping. # HIPAA (/codex/hipaa) HIPAA covers protected health information (PHI) for any company that's a Covered Entity (most healthcare providers, insurers, clearinghouses) or a Business Associate (SaaS vendors processing PHI on behalf of a Covered Entity). If your customers are healthcare orgs and your product touches PHI, you're a Business Associate and HIPAA applies. ## Two main rule sets [#two-main-rule-sets] | Rule | What it covers | Auto-evidence opportunity | | ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | | **Security Rule** | Administrative, physical, and technical safeguards for ePHI | High — \~70% auto-evidenced (mirrors SOC 2 / ISO 27001 controls) | | **Privacy Rule** | Use and disclosure of PHI, patient rights, authorizations | Lower — mostly process + record-keeping | | **Breach Notification Rule** | What to do when PHI is exposed | Process + ticketing-system records | Most SaaS Business Associates focus on Security Rule compliance. Privacy Rule responsibilities typically flow back to the Covered Entity (your customer). ## Security Rule mapping [#security-rule-mapping] The Security Rule has 18 standards across 3 categories. Codex maps each to live evidence: ### Administrative safeguards (§ 164.308) [#administrative-safeguards--164308] | Standard | Codex evidence | | ------------------------------------------------- | ------------------------------------------------------------------------- | | **§ 164.308(a)(1)** Security management process | Risk assessment cadence + remediation tracking from your ticketing system | | **§ 164.308(a)(3)** Workforce security | IdP user lifecycle (provisioning + termination logs) | | **§ 164.308(a)(4)** Information access management | Per-app role assignments + access reviews | | **§ 164.308(a)(5)** Security awareness training | LMS completion records | | **§ 164.308(a)(6)** Security incident procedures | Incident tickets with timestamps, severity, resolution | | **§ 164.308(a)(7)** Contingency plan | Backup schedules + restore-test results | | **§ 164.308(a)(8)** Evaluation | Codex itself is your evaluation tool — exports prove ongoing review | ### Physical safeguards (§ 164.310) [#physical-safeguards--164310] | Standard | Evidence | | ------------------------------------------ | ------------------------------------------------------------------------------ | | **§ 164.310(a)** Facility access controls | Badge system logs (if integrated); office walk-through checklist for SaaS-only | | **§ 164.310(b)** Workstation use | MDM device inventory with PHI-handling devices flagged | | **§ 164.310(c)** Workstation security | MDM screen-lock + auto-lock policy enforcement | | **§ 164.310(d)** Device and media controls | MDM-reported disk encryption + secure-wipe logs on offboarded devices | ### Technical safeguards (§ 164.312) [#technical-safeguards--164312] | Standard | Evidence | | ------------------------------------------------ | ----------------------------------------------------------------- | | **§ 164.312(a)** Access control | IdP MFA enforcement, role-based access from SaaS connectors | | **§ 164.312(b)** Audit controls | SIEM event log retention + activity-log integrity | | **§ 164.312(c)** Integrity | File-integrity monitoring on PHI stores (cloud connector reports) | | **§ 164.312(d)** Person or entity authentication | IdP MFA reports | | **§ 164.312(e)** Transmission security | TLS coverage scan across all PHI-handling endpoints | ## Business Associate Agreements (BAAs) [#business-associate-agreements-baas] Every vendor that touches PHI on your behalf needs a signed BAA. Codex tracks BAA status alongside vendor metadata: * BAA signed: ✓ with date, version, expiration * BAA pending: ✓ with vendor, requester, target sign-by date * BAA not required: ✓ with justification (vendor never sees PHI) When your customer asks for your BAA inventory, **Reports → BAA report** outputs a current snapshot. ## What HIPAA doesn't have (vs SOC 2 / ISO) [#what-hipaa-doesnt-have-vs-soc-2--iso] * **No formal certification** — you can't get "HIPAA certified" by an external auditor; you self-attest. This makes Codex evidence even more important: it's the only artifact proving you actually do what you claim. * **No prescribed audit cadence** — but you should run an annual internal review and publish a SOC 2 + HITRUST or ISO 27001 + HIPAA mapping for serious healthcare buyers. ## Recommended layered approach [#recommended-layered-approach] If you're selling into healthcare: 1. **Year 1**: SOC 2 Type II + HIPAA Security Rule attestation. Most healthcare buyers accept this combo. 2. **Year 2**: Add HITRUST CSF certification (a healthcare-specific compliance framework that maps to HIPAA + ISO + SOC 2 + state laws). Codex's existing evidence mostly carries over. 3. **Year 3**: ISO 27001 if you sell internationally. Codex tracks all three in parallel without duplicate work — controls that satisfy multiple frameworks are tagged once and counted across each report. ## When you're ready [#when-youre-ready] **Reports → HIPAA security rule attestation** outputs: * Per-standard implementation evidence * BAA inventory * Risk assessment + risk register * Incident response history * Workforce training completion This is what your customer's procurement/security team will ask for during their vendor risk review. # Axiom Codex (/codex) Pick a tier, download your first dataset, and run a query. Browse the eight Codex datasets — structured, AI-labeled, and joinable by construction. The APRS contract every record satisfies. The shared keys that make cross-dataset joins work without wrangling. ## One standard, eight datasets [#one-standard-eight-datasets] New datasets, schema changes, and fixes land weekly — follow Codex release notes in the [changelog](/changelog). # ISO 27001 evidence catalog (/codex/iso27001-evidence-catalog) This page lists the highest-traffic ISO 27001:2022 Annex A controls and the exact evidence Codex collects for each. Companion to the [ISO 27001 framework guide](/codex/iso27001). ## Theme A.5 — Organizational controls [#theme-a5--organizational-controls] ### A.5.7 — Threat intelligence [#a57--threat-intelligence] | Source | API call | Cadence | | ----------- | ---------------------------------------------- | ------------- | | CrowdStrike | `/intel/queries/indicators/v1` | Daily | | SentinelOne | `/web/api/v2.1/threat-intelligence/indicators` | Daily | | Wiz | `/api/v1/issues?type=THREAT` | Every 6 hours | Auditors look for: documented threat intel feed configured AND evidence the team reviews/acts on it. Codex tracks both ingestion cadence and ticket-creation rate against incoming threats. ### A.5.16 — Identity management [#a516--identity-management] Same evidence as SOC 2 CC6.1. Codex pulls IdP user creation logs (Google Admin SDK, Microsoft Graph audit logs, Okta `/api/v1/logs?filter=eventType eq "user.lifecycle.create"`) and matches each provisioning event to the HRIS new-hire record. ### A.5.18 — Access rights [#a518--access-rights] Quarterly access review snapshot exported as the ISMS access-review record. Per-user, per-app role table with reviewer attestation timestamp. ### A.5.23 — Information security for use of cloud services [#a523--information-security-for-use-of-cloud-services] Cloud baseline configuration evidence per CSP: * **AWS**: Config rules + Security Hub findings + IAM Access Analyzer * **GCP**: Security Command Center findings + Asset Inventory baseline * **Azure**: Defender for Cloud secure score + Policy compliance Per-CSP baseline drift report shows configurations changed vs documented baseline. ### A.5.24-27 — Information security incident management [#a524-27--information-security-incident-management] Per-incident evidence pulled from PagerDuty / Linear / Jira: * Incident detection time (alert fired) * Acknowledgment time (oncall paged) * Resolution time * Post-mortem document link * Root cause + corrective action Aggregate metrics (MTTR by severity, incident volume trends) for ISMS reporting. ## Theme A.6 — People controls [#theme-a6--people-controls] ### A.6.1 — Screening [#a61--screening] HRIS connector pulls background-check completion records for each new hire: * Hire date * Background check vendor (Checkr, Sterling, etc.) * Check completion date * Status (clear, with-flags, declined) Auditors look for: every active employee has a completed check on file before their start date OR documented exception with risk acceptance. ### A.6.3 — Information security awareness, education and training [#a63--information-security-awareness-education-and-training] LMS connector pulls per-user training completion: * Course name (Security Awareness, GDPR, HIPAA, role-specific) * Completion date * Score (where applicable) * Cadence: annual mandatory + new-hire onboarding ### A.6.5 — Responsibilities after termination [#a65--responsibilities-after-termination] The killer evidence: HRIS termination → IdP deactivation gap report (same as SOC 2 CC6.6). ```text Termination event: 2026-04-15 17:00 UTC (BambooHR: bob@company.com) IdP deactivation: 2026-04-15 17:08 UTC (Okta: bob@company.com) Gap: 8 minutes ✓ (under 24h SLA) Asset return: 2026-04-16 (MDM: 3 devices wiped + reassigned) ``` ## Theme A.8 — Technological controls (highest density) [#theme-a8--technological-controls-highest-density] ### A.8.1 — User endpoint devices [#a81--user-endpoint-devices] MDM device inventory with: * Compliance state per device * Last check-in time * Encryption status (FileVault, BitLocker) * OS patch level vs latest Filtered by org unit + assigned user for risk segmentation. ### A.8.5 — Secure authentication [#a85--secure-authentication] | Source | Evidence | | ---------------- | ------------------------------------------------------------------- | | Okta | MFA enrollment per user; auth policy strength per app | | Google Workspace | 2-Step Verification status per user; Advanced Protection enrollment | | Microsoft Entra | Conditional access policy effectiveness; sign-in risk reports | Auditors specifically want: MFA enrollment rate ≥ 95% across active users, exceptions documented. ### A.8.7 — Protection against malware [#a87--protection-against-malware] EDR coverage from CrowdStrike / SentinelOne: * Endpoints with EDR installed (% coverage) * Endpoints with stale definitions (% out-of-date) * Detected threats in period + remediation outcomes ### A.8.8 — Management of technical vulnerabilities [#a88--management-of-technical-vulnerabilities] Multi-source vulnerability roll-up: * **Snyk / GitHub Dependabot**: dependency CVEs * **Wiz / Orca / Aqua**: cloud workload + IaC findings * **Qualys / Tenable**: infrastructure scans * **Nuclei / OWASP ZAP**: web app scans Per-finding lifecycle: discovered → triaged → remediated, with SLA tracking by severity (Critical 7d, High 30d, Moderate 90d). ### A.8.9 — Configuration management [#a89--configuration-management] | Source | Evidence | | ------------------- | -------------------------------- | | AWS Config | Per-resource baseline drift | | GCP Asset Inventory | Resource state changes | | Azure Policy | Compliance score per policy | | Terraform Cloud | Plan/apply log + drift detection | Configuration changes correlate to PRs in code host (CM-3 from NIST). ### A.8.13 — Information backup [#a813--information-backup] Backup snapshot history per cloud connector + restore-test attestation log. ```text Resource: prod-database (RDS instance) Backup type: Automated daily snapshots + weekly cross-region Retention: 30 days Last successful backup: 2026-04-17 02:00 UTC Last restore test: 2026-03-15 (passed, RPO < 5 min) Next scheduled restore test: 2026-06-15 ``` ### A.8.15 — Logging [#a815--logging] SIEM coverage report per system + per event type: * Auth events (success, failure, MFA bypass) * Configuration changes * Privileged operations * Data access (read/write) Coverage gaps surfaced as exceptions. ### A.8.20-23 — Network security [#a820-23--network-security] Cloud connector pulls VPC config, security group rules, WAF policies, and network segmentation diagrams (DNS records + service mesh config). ### A.8.24 — Use of cryptography [#a824--use-of-cryptography] | Asset class | Evidence | | ------------------ | ------------------------------------------------------------------- | | TLS endpoints | TLS 1.2+ enforcement; weak cipher absence; cert expiration tracking | | At-rest encryption | Per-resource encryption config (RDS KMS, S3 SSE, etc.) | | Key management | KMS key inventory + rotation history | ### A.8.25-29 — Secure development lifecycle [#a825-29--secure-development-lifecycle] GitHub / GitLab connector pulls: * Branch protection rules per repo * Required reviewer count + status * CI status enforcement (tests must pass, security scans must pass) * Secret-detection (GitHub Secret Scanning, GitGuardian) findings + remediation * Code review participation rates per developer ### A.8.31 — Separation of dev / test / prod [#a831--separation-of-dev--test--prod] Cloud account/project separation evidence: * Dev resources in dev account, prod in prod account * IAM roles cannot cross account boundaries * Network isolation between environments ## What this catalog isn't [#what-this-catalog-isnt] This is the technical-control bucket — about 35 of Annex A's 93 controls. The other \~58 (organizational policy, HR process, supplier mgmt, physical security) are tracked in Codex via document links + manual attestations + assigned owners. See the [ISO 27001 framework guide](/codex/iso27001) for the full mapping. # ISO 27001:2022 (/codex/iso27001) ISO 27001:2022 is the international standard for information security management systems (ISMS). The 2022 revision restructured Annex A from 114 controls in 14 domains down to **93 controls in 4 themes**. Codex maps to the 2022 revision. ## ISO 27001 vs SOC 2 [#iso-27001-vs-soc-2] | | ISO 27001 | SOC 2 | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | | **Body** | International (ISO/IEC) | American (AICPA) | | **Audience** | EU, APAC, increasingly North America | North America, US-centric | | **Structure** | ISMS (process) + Annex A (93 controls) | Trust Service Criteria (5 categories, \~60 controls) | | **Certification** | Multi-year (3-year cert with annual surveillance audits) | Annual (Type II is a 6-12 month observation window per audit) | | **Customer demand** | Required by EU enterprise, APAC government | Required by North American enterprise SaaS buyers | | **Overlap with SOC 2** | \~70% — most controls map directly | Reverse: SOC 2 covers most ISO domains | **If you sell internationally, you need both.** Codex maintains the mapping so evidence collected for SOC 2 also satisfies the equivalent ISO 27001 control. No duplicate work. ## The 4 themes (Annex A 2022) [#the-4-themes-annex-a-2022] ### Theme A.5 — Organizational controls (37 controls) [#theme-a5--organizational-controls-37-controls] Policy framework, roles, supplier management, incident management. Codex auto-evidences: * **A.5.7** Threat intelligence — feed from CrowdStrike/SentinelOne/Wiz * **A.5.10** Acceptable use — link to your published AUP + training completion * **A.5.16** Identity management — IdP user provisioning logs * **A.5.18** Access rights — per-app role assignments from IdP * **A.5.23** Cloud services info security — AWS/GCP/Azure security baseline configs * **A.5.24-27** Incident management — ticketing system events with timestamps and resolutions Manual: A.5.1 (policies), A.5.2 (roles), A.5.4 (management direction), A.5.19-22 (supplier security — vendor questionnaires). ### Theme A.6 — People controls (8 controls) [#theme-a6--people-controls-8-controls] HR security: screening, terms of employment, training, disciplinary process. Codex auto-evidences: * **A.6.1** Screening — background check completion from BambooHR/Rippling/Gusto HRIS connector * **A.6.3** Information security awareness — LMS training completion records * **A.6.5** Responsibilities after termination — HRIS termination → IdP deactivation diff (proves access removal SLA) Manual: A.6.2 (terms of employment — contract template), A.6.4 (disciplinary), A.6.7-8 (remote work + reporting). ### Theme A.7 — Physical controls (14 controls) [#theme-a7--physical-controls-14-controls] Facility security, equipment, removable media. Mostly relevant if you have offices/datacenters; SaaS-only companies often scope these out. Codex auto-evidences: * **A.7.1-2** Physical security perimeter + entry — badge system logs (where integrated) * **A.7.7** Clear desk/clear screen — MDM screen lock policy + idle timeout enforcement Manual: most A.7 controls are policy + occasional inspection (you walk the office, take photos, attest annually). ### Theme A.8 — Technological controls (34 controls) [#theme-a8--technological-controls-34-controls] The biggest auto-evidence opportunity. Network, endpoint, cryptography, application security, logging. Codex auto-evidences (heavy auto-fill area): | Control | Evidence | | ------------------------------------------ | ------------------------------------------------------------------------ | | **A.8.1** User endpoint devices | MDM device inventory with compliance state | | **A.8.2** Privileged access rights | Admin role assignments across IdP, cloud, code, SaaS | | **A.8.3** Information access restriction | Per-app access control configs + DLP rules | | **A.8.5** Secure authentication | IdP MFA enforcement, password policy, SSO coverage | | **A.8.6** Capacity management | Cloud-monitor metrics (CPU, memory, disk, request volume) | | **A.8.7** Protection against malware | EDR coverage from CrowdStrike/SentinelOne | | **A.8.8** Vulnerability management | Snyk/Wiz/Dependabot findings + remediation timelines | | **A.8.9** Configuration management | Cloud config drift from baseline (AWS Config, GCP Asset Inventory) | | **A.8.10** Information deletion | Backup retention configs + deletion logs | | **A.8.11** Data masking | DLP rules from Workspace/M365 | | **A.8.12** Data leakage prevention | DLP rule violations + remediation | | **A.8.13** Backup | Backup snapshot history + restore test logs | | **A.8.15** Logging | SIEM event collection coverage | | **A.8.16** Monitoring activities | Alert rules + on-call ticket history | | **A.8.20-23** Network controls | Cloud VPC config, security groups, WAF rules | | **A.8.24** Cryptographic controls | TLS coverage report + at-rest encryption status | | **A.8.25-29** Secure development lifecycle | GitHub branch protection, PR review, security scanning, secret-detection | | **A.8.30** Outsourced development | Same as A.8.29 if you use contract devs in your codebase | | **A.8.31** Separation of dev/test/prod | Cloud account/project separation | ## Statement of Applicability (SoA) [#statement-of-applicability-soa] ISO 27001 requires you to publish a **Statement of Applicability** documenting which Annex A controls apply, why, and how they're implemented. Codex generates a draft SoA from your evidence: * Controls auto-evidenced → marked "applicable + implemented" with evidence source * Controls assigned to humans → marked "applicable + implemented" with link to evidence repo * Controls you've explicitly excluded → marked "not applicable" with required justification Edit the draft, save, and export. The auditor wants to see this document — Codex makes it real-time accurate instead of a stale spreadsheet. ## Setup order [#setup-order] Same as SOC 2 — start with IdP, then MDM, then code host, then ticketing, then cloud. You'll cover \~75% of A.5 + A.6 + A.8 in the first month. ## When you're ready for the auditor [#when-youre-ready-for-the-auditor] **Reports → ISO 27001 evidence package** outputs: * Statement of Applicability (current state) * Per-control evidence snapshots * Risk treatment plan + risk register (you import these from your existing risk-mgmt process) * Internal audit findings + management review minutes Most ISO 27001 auditors accept Codex packages directly; some require evidence in their own portal — Codex CSV export covers that. # Cross-dataset join keys (/codex/join-keys) Codex datasets are designed so any two can join without custom wrangling. This page documents the keys that make that possible, which datasets carry which keys, and how to use them. ## The keys [#the-keys] | Key | Type | Format | Used for | | ------------------- | ------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `record_id` | URN | `urn:aprs:record:{namespace}:{source_system}:{local_id}` | Stable identity across re-ingests. Primary key within a dataset. | | `chunk_id` | URN | `urn:aprs:chunk:{hex16}` | Vector-index key. Deterministic SHA-256 of `record_id` + section. | | `h3_index` | string | H3 resolution-8 cell (e.g. `88283082b9fffff`) | Spatial join across any geospatial datasets. | | `event_id` | UUID | Standard UUIDv4 | Joins Events Timeline to any dataset that emits events. | | `jurisdiction_slug` | string | `{city-slug}-{state-abbr}` (e.g. `philadelphia-pa`) | Civic-layer joins across city, county, and state boundaries. | | `mmsi` | string | 9-digit Maritime Mobile Service Identity | AIS position to vessel joins. Not stable across re-registrations — use `imo` when you need permanence. | | `imo` | integer | 7-digit IMO number | Vessel identity across ownership, flag, and name changes. Primary vessel key. | | `poi_id` | URN | `urn:aprs:record:poi:{source_system}:{local_id}` | POI joins across datasets. | | `parcel_id` | string | `{jurisdiction_slug}:{parcel-number}` | Parcel-level real-estate joins. | | `entity_urn` | URN | `urn:aprs:entity:{type}:{canonical-id}` | Entity resolution across sources (person, company, agency, vessel, etc.). | ## Key availability by dataset [#key-availability-by-dataset] | Dataset | `h3_index` | `event_id` | `jurisdiction_slug` | `mmsi` | `imo` | `poi_id` | `parcel_id` | `entity_urn` | | ------------------- | :--------: | :--------: | :-----------------: | :----: | :---: | :------: | :---------: | :----------: | | Civic Intelligence | yes | yes | yes | — | — | — | opt. | yes | | Events Timeline | yes | PK | yes | opt. | opt. | opt. | opt. | yes | | Urban Signal Grid | PK | — | yes | — | — | — | — | — | | POI Intelligence | yes | — | yes | — | — | PK | — | — | | AIS Maritime | — | yes | — | yes | yes | — | — | yes | | LEHD Commuter Flows | yes | — | yes | — | — | — | — | — | | Permit Signals | yes | yes | yes | — | — | — | yes | yes | | OSHA Safety Index | yes | — | yes | — | — | — | — | yes | **PK** = primary key. **opt.** = emitted when the relevant entity is known. **—** = not applicable. ## Join examples [#join-examples] ### Civic decisions in high-signal cells [#civic-decisions-in-high-signal-cells] Join Civic Intelligence to Urban Signal Grid via `h3_index` to find recent zoning decisions in high-scoring cells: ```sql SELECT cells.h3_index, cells.composite_score, civic.event_type, civic.occurred_at, civic.litigation_risk_score FROM codex.urban_signal_grid cells JOIN codex.civic_intelligence civic USING (h3_index) WHERE civic.event_type IN ('zoning_vote', 'rezoning_hearing') AND civic.occurred_at >= '2026-01-01' AND cells.composite_score > 0.7; ``` ### Full event detail for a jurisdiction [#full-event-detail-for-a-jurisdiction] Join Events Timeline to Civic Intelligence via `event_id` to get entities, blockers, and hostility scores for civic events: ```sql SELECT e.event_id, e.occurred_at, e.category, c.entities_extracted, c.blockers, c.hostility_index FROM codex.events_timeline e JOIN codex.civic_intelligence c USING (event_id) WHERE e.jurisdiction_slug = 'philadelphia-pa' AND e.occurred_at >= '2026-03-01'; ``` ### Vessel positions around dark events [#vessel-positions-around-dark-events] Join AIS Maritime to Events Timeline via `event_id` to find vessels and their positions around Overwatch dark events: ```sql SELECT e.event_id, e.occurred_at, ais.mmsi, ais.imo, ais.lat, ais.lng, ais.speed FROM codex.events_timeline e JOIN codex.ais_maritime ais USING (event_id) WHERE e.category = 'dark_event' ORDER BY e.occurred_at DESC; ``` ### Commuter inflow to high-signal cells [#commuter-inflow-to-high-signal-cells] Join LEHD Commuter Flows to Urban Signal Grid via `h3_index`: ```sql SELECT g.h3_index AS destination_h3, g.composite_score, SUM(l.worker_count) AS inbound_workers FROM codex.urban_signal_grid g JOIN codex.lehd_commuter_flows l ON g.h3_index = l.destination_h3 GROUP BY g.h3_index, g.composite_score; ``` ## Joins that will not work [#joins-that-will-not-work] | Attempted join | Why it fails | Use instead | | --------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `lat`, `lng` equality | Floating-point equality is unsafe; sources round differently | `h3_index` | | `vessel_name` | Names change with ownership and flag. Not unique. | `imo` | | Source-native IDs across datasets | Different sources use different IDs for the same entity | `entity_urn` | | Date-only joins | Time zones and publication lag make cross-dataset alignment unreliable | Join on key + temporal filter (e.g. `ABS(a.occurred_at - b.occurred_at) < interval '7 days'`) | ## Key construction rules [#key-construction-rules] ### `h3_index` [#h3_index] Always resolution 8. Stored as the canonical H3 hexadecimal string (e.g. `88283082b9fffff`). When a record covers an area, the dataset either emits a separate row per H3 cell or an array column `h3_indexes` — the choice is documented in each dataset's schema. ### `jurisdiction_slug` [#jurisdiction_slug] Lowercase, hyphen-separated: * **Cities:** `{city}-{state-abbr}` (e.g. `philadelphia-pa`, `san-francisco-ca`) * **Counties:** `{county}-county-{state-abbr}` (e.g. `harris-county-tx`) * **States:** `{state-full-name}` (e.g. `texas`) * **Special districts:** `{name}-{state-abbr}` (e.g. `port-authority-ny`) ### `mmsi` vs. `imo` [#mmsi-vs-imo] `mmsi` is the runtime identifier on every AIS position — use it for linking positions to vessel records during ingest. `imo` is the permanent vessel identifier (IMO A.600) that survives ownership, flag, and name changes. Use `imo` as the primary vessel key when available. Vessels without an IMO number (some fishing vessels and small craft) carry `has_imo=false`. ### `entity_urn` [#entity_urn] Format: `urn:aprs:entity:{type}:{canonical-id}` where `type` is one of `person`, `company`, `agency`, `trust`, `vessel`, or `nonprofit`. Two source records share the same `entity_urn` when Codex entity resolution determines they refer to the same real-world entity. # NIST 800-53 (/codex/nist-800-53) NIST 800-53 is the catalog of security and privacy controls used by US federal information systems. If you sell SaaS to federal contractors, defense contractors, or directly to agencies, you'll encounter it in two ways: 1. **Indirectly** — via FISMA, FedRAMP, DoD CMMC, and HIPAA all of which derive from 800-53 2. **Directly** — when a federal customer requires you implement specific 800-53 controls in your environment The catalog has 1,189 controls across 20 control families. You don't implement all of them — you scope to a baseline (Low / Moderate / High) based on the impact level of the data you handle. ## Baselines [#baselines] | Baseline | Control count | Use case | | ------------ | -------------- | ------------------------------------------------------------------------- | | **Low** | \~149 controls | Public-facing data, low-impact systems | | **Moderate** | \~287 controls | Internal data, most SaaS scenarios — **the default for FedRAMP Moderate** | | **High** | \~370 controls | Sensitive data, mission-critical systems — military, intelligence | For most SaaS companies entering the federal market, **Moderate is the target**. It maps closely to FedRAMP Moderate and CMMC Level 2. ## How Codex maps the high-leverage families [#how-codex-maps-the-high-leverage-families] ### AC — Access Control (25 controls in Moderate baseline) [#ac--access-control-25-controls-in-moderate-baseline] | Control | Codex evidence | | ------------------------------------ | --------------------------------------------------------------------------------------------------- | | **AC-2** Account Management | IdP user lifecycle (provisioning, modification, termination logs from Google Workspace, M365, Okta) | | **AC-3** Access Enforcement | App-level role assignments + RLS policy reviews from cloud connector | | **AC-6** Least Privilege | Privileged-access reports per app (admin counts, named admins) | | **AC-7** Unsuccessful Logon Attempts | IdP failed-auth event volume from SIEM connector | | **AC-11** Session Lock | MDM screen-lock policy enforcement (FileVault auto-lock, BitLocker session timeout) | | **AC-17** Remote Access | VPN config + session logs from cloud or VPN connector | ### AU — Audit and Accountability (12 controls in Moderate) [#au--audit-and-accountability-12-controls-in-moderate] | Control | Evidence | | ---------------------------------------- | ------------------------------------------------------------------------ | | **AU-2** Event Logging | SIEM connector event coverage report — what's logged, what isn't | | **AU-4** Audit Storage Capacity | Cloud-storage retention configs for log archives | | **AU-9** Protection of Audit Information | CloudTrail / Activity Log immutability config | | **AU-12** Audit Record Generation | Per-system logging-enabled audit (each cloud account, each prod service) | ### CM — Configuration Management (10 controls in Moderate) [#cm--configuration-management-10-controls-in-moderate] | Control | Evidence | | ------------------------------------- | -------------------------------------------------------------------------- | | **CM-2** Baseline Configuration | Terraform/IaC commit history — your declared baseline | | **CM-3** Configuration Change Control | Merged PR records with reviewer + CI status | | **CM-7** Least Functionality | Cloud security group config (open ports, allowed protocols) | | **CM-8** System Component Inventory | The thing Layer is for. Every device, app, license, user, with timestamps. | ### CP — Contingency Planning (9 controls in Moderate) [#cp--contingency-planning-9-controls-in-moderate] | Control | Evidence | | ------------------------- | ------------------------------------------------------------------------- | | **CP-2** Contingency Plan | Linked Notion / Google Doc + last review timestamp | | **CP-9** System Backup | Backup snapshot history from cloud connector | | **CP-10** System Recovery | Restore-test results (manually uploaded with timestamp + tester identity) | ### IA — Identification and Authentication (12 controls in Moderate) [#ia--identification-and-authentication-12-controls-in-moderate] | Control | Evidence | | ---------------------------------------------------------- | --------------------------------------------------------------------------- | | **IA-2** Identification and Authentication | IdP MFA enforcement reports | | **IA-5** Authenticator Management | Password policy config + rotation enforcement | | **IA-8** Identification and Authentication (Non-Org Users) | External-user inventory (Slack-Connect, GitHub outside collaborators, etc.) | ### IR — Incident Response (9 controls in Moderate) [#ir--incident-response-9-controls-in-moderate] | Control | Evidence | | ------------------------------- | --------------------------------------------------------------- | | **IR-4** Incident Handling | Per-incident timeline from PagerDuty / Linear / Jira | | **IR-5** Incident Monitoring | Aggregate incident metrics (volume, severity, MTTR per quarter) | | **IR-8** Incident Response Plan | Linked plan + last review timestamp | ### RA — Risk Assessment (5 controls in Moderate) [#ra--risk-assessment-5-controls-in-moderate] | Control | Evidence | | ---------------------------------------------- | ----------------------------------------------------------------- | | **RA-3** Risk Assessment | Linked risk register + last update timestamp | | **RA-5** Vulnerability Monitoring and Scanning | Snyk/Wiz/Dependabot findings + remediation timelines per severity | ### SC — System and Communications Protection (24 controls in Moderate) [#sc--system-and-communications-protection-24-controls-in-moderate] | Control | Evidence | | ------------------------------------------- | ------------------------------------------------ | | **SC-7** Boundary Protection | Cloud security groups + WAF config | | **SC-8** Transmission Confidentiality | TLS coverage report | | **SC-13** Cryptographic Protection | KMS config + algorithms in use | | **SC-28** Protection of Information at Rest | At-rest encryption config across all data stores | ### SI — System and Information Integrity (15 controls in Moderate) [#si--system-and-information-integrity-15-controls-in-moderate] | Control | Evidence | | ---------------------------------- | ------------------------------------------------------------------------- | | **SI-2** Flaw Remediation | Patch management cadence (OS patch level from MDM, dependency-update PRs) | | **SI-3** Malicious Code Protection | EDR coverage from CrowdStrike / SentinelOne | | **SI-4** System Monitoring | SIEM event collection coverage + alert rules | ## What Codex doesn't replace [#what-codex-doesnt-replace] NIST 800-53 has a heavy **policy + process** component that Codex doesn't auto-generate: * **PL** Planning controls — your System Security Plan (SSP) is a 100+ page document describing every control's implementation. Codex provides the evidence; you write the prose. * **PM** Program Management controls — organization-wide program (CISO function, threat awareness program, etc.). Pure organizational design. * **PS** Personnel Security controls — background checks, position designation. HR-system data, mostly manual. Codex's role: provide the technical evidence for \~70% of the catalog. Your security team writes the SSP, conducts the assessments, and engages the assessor. ## Connection to FedRAMP [#connection-to-fedramp] If you want to sell to federal agencies directly (not just contractors), you need **FedRAMP authorization** — a formal third-party assessment of your 800-53 implementation. Three paths: 1. **FedRAMP Tailored** — for low-impact SaaS (think: simple form-collection apps). \~120 controls. \~6 months, \~$50K-100K. 2. **FedRAMP Moderate** — the default for most B2B SaaS to federal. \~325 controls. \~12-18 months, \~$300K-500K. 3. **FedRAMP High** — only for sensitive workloads. \~410 controls. \~18-24 months, \~$500K-1M. See the [FedRAMP guide](/codex/fedramp) for the authorization workflow. ## When you're ready [#when-youre-ready] **Reports → NIST 800-53 evidence package** outputs: * Per-control implementation evidence with timestamps * Control inheritance map (which controls rely on which CSP — AWS GovCloud, Azure Government — vs your application's implementation) * Continuous monitoring metrics (the ConMon report federal customers expect monthly) * Plan of Action and Milestones (POAM) for any controls you've documented as exceptions # Normalization standard (/codex/normalization-standard) The AI-Ready Public Record Standard (APRS) defines the minimum contract every record in every Codex dataset must satisfy. It exists so you can join any two Codex datasets without wrangling code, pin a dataset to a schema version and trust forward compatibility, and feed records directly into an LLM, RAG index, or training pipeline. ## Principles [#principles] Every Codex dataset conforms to seven principles: 1. **Schema-locked.** Every dataset publishes a versioned schema. Breaking changes bump the major version. You pin to a version and trust forward compatibility within a major. 2. **Source-attributed.** Every record carries provenance — what system emitted it, when, which pipeline version processed it, and a confidence score. 3. **AI-optimized labels.** Categories, entity types, and sentiment labels are pre-computed at normalization time, not at query time. 4. **Spatially consistent.** All geospatial data normalizes to H3 resolution 8 as the primary spatial key. Lat/lng is retained for display, not for joining. 5. **Bitemporally honest.** Every record separates valid time (when the real-world event happened) from system time (when it was ingested or modified). 6. **Versioned snapshots.** Monthly immutable snapshot releases with full changelogs. Pin to a month for reproducible research. 7. **Joinable by construction.** A fixed set of [shared keys](/codex/join-keys) lets any dataset join to any other without custom wrangling. ## Record envelope [#record-envelope] Every record carries four groups of mandatory fields, applied at normalization time. ### Identity [#identity] | Field | Type | Description | | --------------- | ---------- | ------------------------------------------------------------------------------------------ | | `record_id` | URN | Stable record URN: `urn:aprs:record:{namespace}:{source_system}:{local_id}` | | `chunk_id` | URN | Deterministic chunk URN derived from `record_id` + optional section label (SHA-256-backed) | | `source_uri` | URL or URN | Points to the original source record for citation and re-fetch | | `source_system` | string | Originating system name (e.g. `granicus`, `aisstream`, `equasis`) | `record_id` and `chunk_id` are deterministic — two calls with the same arguments always produce the same URN. This enables incremental sync, deduplication, and stable vector index keys. ### Schema and lineage [#schema-and-lineage] | Field | Type | Description | | ----------------------- | ------ | ---------------------------------------------------------------------------------- | | `schema_version` | semver | APRS profile version, e.g. `aprs.civic/1.0.0` | | `normalization_version` | semver | Version of the pipeline that produced this row | | `acl_tier` | enum | `research`, `commercial`, or `internal` — gates which exports may include this row | ### Bitemporal fields [#bitemporal-fields] | Field | Type | Description | | ---------------- | -------- | ----------------------------------------------------------------------------------------------- | | `ingested_at` | ISO 8601 | When the system first ingested this row. Never mutates after insert. | | `modified_at` | ISO 8601 | When the row was last updated. Refreshed on any write. | | `occurred_at` | ISO 8601 | When the real-world event happened (e.g. council vote date, AIS position timestamp) | | `filed_at` | ISO 8601 | When the record was filed or submitted to the authority. Required for permits and OSHA records. | | `published_at` | ISO 8601 | When the source authority published the record | | `effective_from` | ISO 8601 | When a ruling or record became legally effective. Null if not applicable. | | `effective_to` | ISO 8601 | When it expired or was superseded. Null means currently active. | See the [bitemporal fields reference](/codex/bitemporal-fields) for per-dataset availability and domain-specific temporal extensions. A permit can be voted on (`occurred_at`), published weeks later (`published_at`), become legally effective months after that (`effective_from`), and be ingested by Codex retroactively (`ingested_at`). Choose the clock that matches your analysis. ### Confidence and provenance [#confidence-and-provenance] | Field | Type | Description | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------- | | `confidence_score` | float \[0,1] | Normalizer's confidence in the record. Methodology is documented per-dataset. | | `provenance` | JSON array | Ordered list of transformations: `[{stage, version, ts, notes?}]` for full lineage reconstruction | ## Spatial consistency [#spatial-consistency] All geospatial data includes `h3_index` at resolution 8 (avg edge length \~461 m, cell area \~0.74 km²). This is the universal spatial join key across all Codex datasets. * **Point geometry** — `h3_index` is the H3 cell containing the point. * **Polygon geometry** — `h3_indexes` (array) covers the polygon at resolution 8. `geometry_wkt` is retained for display. * **Line geometry** — H3 cells intersecting the line buffer. Higher or lower resolutions may be published as supplementary fields (`h3_index_9`, etc.), but resolution 8 is authoritative. ## LLM-ready surface [#llm-ready-surface] Every dataset publishes a `llm_text` view in Markdown-KV format alongside the structured Parquet/CSV view. This format is optimized for LLM reasoning — benchmarked at 60.7% accuracy versus 44.3% for CSV. ```markdown - chunk_id: urn:aprs:chunk:9f3a1b2c... - record_id: urn:aprs:record:civic:us:granicus:phila-2024-03-15-item7b - jurisdiction: Philadelphia, PA - occurred_at: 2024-03-15 - event_type: zoning_vote - summary: Council voted 11-6 to approve rezoning of the 2200 block... - entities: {name: Kenyatta Johnson, role: councilmember, sentiment: supportive} - litigation_risk_score: 0.42 - source_uri: https://phlcouncil.com/meetings/... ``` ## Claim vs. fact separation [#claim-vs-fact-separation] For datasets where multiple sources may contradict each other (corporate ownership, permits, civic proceedings), records are published at two layers: * **Claim layer** — what a source asserted, preserved verbatim with source attribution. Multiple claims per subject are expected. * **Fact layer** — Codex's resolution of contradictory claims into a canonical row, with a `resolution_method` field explaining the choice (e.g. `latest_by_published_at`, `authority_priority`, `manual_review`). This separation ensures you can always trace how a fact was derived and which original assertions it is based on. See the [claim/fact separation](/codex/claim-fact-layer) page for full schemas, resolution methods, and query examples. ## Versioning [#versioning] * **Schema semver** — `MAJOR.MINOR.PATCH`. Breaking changes (removing fields, changing types, narrowing enums) bump `MAJOR`. Additive changes bump `MINOR`. Doc-only clarifications bump `PATCH`. * **Normalization semver** — independent of schema version. A normalization version bump is always accompanied by a changelog entry. * **Snapshot releases** — first of each month, immutable once published. Labeled `YYYY-MM`. * **Deprecation** — fields marked `@deprecated` in a `MINOR` release may be removed in the next `MAJOR` with at least 6 months notice. # Reference notebooks (/codex/notebooks) Codex ships two reference notebooks that demonstrate real analytical workflows using the free research-tier datasets on Hugging Face. Both notebooks are licensed CC-BY-4.0, pin to the `2026-04` snapshot, and require no paid tier. Fine-tune DistilBERT on council meeting language to predict zoning outcomes, then benchmark against Codex's pre-computed scores. Build an H3 choropleth of litigation risk and test whether elevated risk predicts slower permit issuance. ## Prerequisites [#prerequisites] Both notebooks require Python 3.10+ and the following core dependencies: ```txt datasets transformers pandas numpy matplotlib h3 plotly scipy ``` The upzoning classifier additionally requires `torch`, `accelerate`, `evaluate`, and `scikit-learn`. The civic risk map additionally requires `geopandas` and `shapely`. You do not need a paid Codex tier. Both notebooks load the 100K-record research sample directly from Hugging Face. ## Upzoning classifier [#upzoning-classifier] **Goal:** Fine-tune a DistilBERT model (\~66M parameters, \~10 minutes on a single GPU) on the `language_signals` and `summary` fields from Civic Intelligence to predict upzoning outcomes (approved, denied, or continued), then compare against Codex's pre-computed `upzoning_probability`. **Datasets used:** [Civic Intelligence](/codex/schemas/civic-intelligence) (research tier) ### Workflow [#workflow] ### Load the research-tier sample [#load-the-research-tier-sample] Load the Civic Intelligence dataset from Hugging Face, pinned to the `2026-04` snapshot: ```python from datasets import load_dataset ds = load_dataset( "axiom-ai/civic-intelligence", revision="snapshot/2026-04", split="train" ) ``` ### Filter to zoning records [#filter-to-zoning-records] Keep only `zoning_vote` and `rezoning_hearing` records with non-null outcomes for training: ```python zoning = ds.filter( lambda r: r["document_type"] in ("zoning_vote", "rezoning_hearing") and r["upzoning_probability"] is not None ) ``` ### Build input features [#build-input-features] Concatenate the top 30 `language_signals` phrases with the `summary` field to create a text input for the classifier: ```python def build_text(row): signals = " | ".join((row["language_signals"] or [])[:30]) return f"signals: {signals}\nsummary: {row['summary'] or ''}" ``` ### Split by jurisdiction [#split-by-jurisdiction] Use a jurisdiction-based train/test split to test generalization — train on Philadelphia, Chicago, and Dallas; evaluate on San Francisco and New York: ```python train_jurisdictions = {"philadelphia-pa", "chicago-il", "dallas-tx"} test_jurisdictions = {"san-francisco-ca", "new-york-ny"} ``` ### Fine-tune DistilBERT [#fine-tune-distilbert] Train for 3 epochs with batch size 16, learning rate 5e-5, and macro-F1 as the evaluation metric. ### Compare against Codex scores [#compare-against-codex-scores] Evaluate your trained classifier against Codex's pre-computed `upzoning_probability` using ROC-AUC on the held-out jurisdictions. ### What you learn [#what-you-learn] * How to load and filter Codex datasets from Hugging Face * How `language_signals` and `summary` power zoning outcome prediction * How Codex's pre-computed scores compare to a custom fine-tuned model * How jurisdiction-based splits reveal geographic generalization gaps ## Civic risk map [#civic-risk-map] **Goal:** Build an H3-cell choropleth of civic litigation risk and test whether elevated risk predicts depressed permit-issuance velocity in the following 6 months. **Datasets used:** [Civic Intelligence](/codex/schemas/civic-intelligence), Urban Signal Grid, Permit Signals (all research tier) ### Workflow [#workflow-1] ### Load three datasets [#load-three-datasets] Load the research-tier samples for Civic Intelligence, Urban Signal Grid, and Permit Signals from Hugging Face: ```python from datasets import load_dataset civic = load_dataset("axiom-ai/civic-intelligence", revision="snapshot/2026-04", split="train") usg = load_dataset("axiom-ai/urban-signal-grid", revision="snapshot/2026-04", split="train") permits = load_dataset("axiom-ai/permit-signals", revision="snapshot/2026-04", split="train") ``` ### Filter to a focus metro [#filter-to-a-focus-metro] Filter all three datasets to a single metro (e.g., `chicago-il`) for tractable analysis. ### Aggregate risk to H3 cells [#aggregate-risk-to-h3-cells] Compute a confidence-weighted mean of `litigation_risk_score` per `h3_index` from the Civic Intelligence dataset: ```python import pandas as pd civic_df = civic.to_pandas() risk_by_cell = ( civic_df .groupby("h3_index") .apply(lambda g: (g["litigation_risk_score"] * g["confidence_score"]).sum() / g["confidence_score"].sum()) .rename("weighted_risk") ) ``` ### Join to Urban Signal Grid [#join-to-urban-signal-grid] Join the aggregated risk scores to the Urban Signal Grid on `h3_index`: ```python usg_df = usg.to_pandas() joined = usg_df.merge(risk_by_cell, on="h3_index", how="left") ``` ### Render an interactive choropleth [#render-an-interactive-choropleth] Materialize H3 hexagon polygons and render a Plotly choropleth colored by litigation risk score. ### Test the risk-to-permits hypothesis [#test-the-risk-to-permits-hypothesis] Compute permit velocity (permits issued per cell in the following 6 months) and run a Spearman correlation test against litigation risk: ```python from scipy.stats import spearmanr rho, p = spearmanr(merged["weighted_risk"], merged["permit_velocity"]) ``` ### What you learn [#what-you-learn-1] * How all three datasets join on `h3_index` alone — no spatial library required * How to aggregate record-level scores to the H3 cell grid * How civic proceedings signal downstream development activity * How to validate Codex scores against observable permit outcomes ## Key takeaway [#key-takeaway] Both notebooks demonstrate the core Codex value proposition: datasets that join by construction, carry pre-computed AI labels, and enable cross-domain analysis without custom ETL. Start with the research tier on Hugging Face and upgrade to Commercial when you need full coverage. # PCI DSS evidence catalog (/codex/pci-dss-evidence-catalog) PCI DSS v4.0 has 12 requirements with \~329 sub-requirements. SaaS at SAQ A-EP scope satisfies \~146 of them. This page lists the highest-traffic sub-requirements and their evidence sources. Companion to the [PCI DSS framework guide](/codex/pci-dss). ## Requirement 1 — Network security controls [#requirement-1--network-security-controls] ### 1.2.5 — Allowed services, protocols, ports [#125--allowed-services-protocols-ports] Cloud connector pulls security group rules per VPC. Codex flags: * Any inbound rule allowing 0.0.0.0/0 on ports other than 80/443 (default-deny exception) * Outbound rules allowing arbitrary destinations * Default security groups in use (vs purpose-built groups per service) ### 1.4 — Network connections between trusted and untrusted networks [#14--network-connections-between-trusted-and-untrusted-networks] Per-environment network segmentation evidence: * CDE (cardholder data environment) accounts/projects vs non-CDE * VPC peering rules between them (only allowlisted services) * Service-to-service authentication enforced (mTLS, IAM roles) ## Requirement 2 — Secure configurations [#requirement-2--secure-configurations] ### 2.2.1 — Configuration standards [#221--configuration-standards] Terraform/Pulumi commit history pulled from code host: * Per-resource baseline (e.g. `aws_db_instance` with required encryption + backup settings) * Drift detection from cloud-config tooling * PR review history showing changes were reviewed ### 2.3 — Default credentials [#23--default-credentials] Cloud IAM inventory + secrets-management connector: * AWS root user — no active access keys (red flag if present) * Database admin passwords — managed via Secrets Manager / Vault, not hardcoded * Application service accounts — have passwords/keys rotated within policy window ## Requirement 3 — Account data protection [#requirement-3--account-data-protection] ### 3.5.1 — PAN encryption / tokenization [#351--pan-encryption--tokenization] For SAQ A and A-EP, you should be tokenizing — Codex looks for direct PAN storage as a critical exception: * Database column scan for PAN-shaped data (16-digit numbers) * Log scan for PAN appearing in application logs (huge red flag) * Cache scan for PAN in Redis/Memcached For SAQ D: direct PAN storage requires KMS + tokenization vault evidence. ### 3.6 — Cryptographic key management [#36--cryptographic-key-management] KMS connector evidence: * Per-key purpose + rotation policy * Key access audit log (who decrypted what, when) * Cryptographic key inventory + lifecycle status ## Requirement 4 — Transmission protection [#requirement-4--transmission-protection] ### 4.2.1 — Strong cryptography on public networks [#421--strong-cryptography-on-public-networks] TLS coverage scan across all public endpoints: * TLS 1.2 minimum (1.3 preferred) * No weak ciphers (RC4, 3DES, NULL, EXPORT) * Certificate validity + expiration tracking * HSTS enforced Per-endpoint compliance status with last-scan timestamp. ## Requirement 5 — Malware protection [#requirement-5--malware-protection] ### 5.2 — Anti-malware on at-risk systems [#52--anti-malware-on-at-risk-systems] EDR coverage from CrowdStrike / SentinelOne: * Coverage rate (% of in-scope endpoints with EDR) * Definitions current (% within 24h of latest) * Detection events + outcomes ## Requirement 6 — Secure system development [#requirement-6--secure-system-development] ### 6.2.4 — Secure coding training [#624--secure-coding-training] LMS records for developers: * OWASP top 10 training * Secure coding course completion * Cadence: annual mandatory ### 6.3.1 — Vulnerability identification [#631--vulnerability-identification] Per-vulnerability lifecycle: Illustrative example — synthetic data; CVE-0000-0000 is a placeholder. ```text CVE: CVE-0000-0000 Discovered: 2026-04-12 (Snyk dependency scan) Severity: High (CVSS 8.4) Affected component: api-gateway → express@4.17.1 Triaged: 2026-04-12 (PR #2143 opened) Resolved: 2026-04-13 (PR merged + deployed to prod) SLA window: 30 days for High ✓ ``` ### 6.4.3 — Public-facing web app protections [#643--public-facing-web-app-protections] WAF connector evidence: * WAF deployed in front of all public web apps * Rule set matches a baseline (OWASP CRS, AWS Managed Rules, Cloudflare Managed) * Rule violations + outcomes (blocked, alerted, allowed) ## Requirement 7 — Access restriction [#requirement-7--access-restriction] ### 7.2 — Role-based access control [#72--role-based-access-control] Per-app role assignments from IdP + cloud + SaaS connectors. PCI-specific cuts: * Per-role: which CDE resources accessible * Per-user: which roles assigned (vs the role baseline for their job function) * Quarterly access review attestations ### 7.3 — Access control system [#73--access-control-system] Default-deny enforcement evidence: * IAM policies use explicit allow + implicit deny (no `*:*` policies) * Network ACLs default-deny * Application authorization checks at every endpoint (code review evidence) ## Requirement 8 — Identification and authentication [#requirement-8--identification-and-authentication] ### 8.3 — Strong authentication for non-CDE [#83--strong-authentication-for-non-cde] IdP MFA enforcement reports filtered to non-CDE-administrating users. ### 8.4 — MFA for CDE access [#84--mfa-for-cde-access] Conditional access policies showing: * All CDE access requires MFA * Specific MFA factor types accepted (no SMS for CDE — must be authenticator app, security key, or biometric) * MFA enrollment rate (must be 100% for CDE-accessing users) ### 8.5 — Multi-step authentication [#85--multi-step-authentication] Per-CDE-user MFA factor inventory: * Primary factor (password + complexity) * Secondary factor type (TOTP, FIDO2, push) * Backup factor (recovery codes) ### 8.6 — Authenticator account management [#86--authenticator-account-management] Service account inventory with last-rotation timestamp + lifecycle status. ## Requirement 10 — Logging and monitoring [#requirement-10--logging-and-monitoring] ### 10.2 — Audit log generation [#102--audit-log-generation] Per-system logging coverage: * Per CDE system: logging enabled, what events, retention period * Per user: per-day activity log inventory * Privileged operations specifically logged (admin actions, schema changes, key access) ### 10.3 — Log integrity [#103--log-integrity] Cloud-config evidence: * CloudTrail / Activity Log → immutable storage (S3 Object Lock, Azure Immutable Blob) * Log forwarding to SIEM with cryptographic verification ### 10.6 — Log review [#106--log-review] Log review activity records: * Who reviewed which log set * When (date + time) * Findings (anomaly count, escalations) PCI requires daily review of critical logs — Codex flags any 24h gap as an exception. ## Requirement 11 — Security testing [#requirement-11--security-testing] ### 11.3 — External vulnerability scans [#113--external-vulnerability-scans] Quarterly ASV (Approved Scanning Vendor) scan reports — you upload them, Codex stores with: * Scan date * ASV vendor name * Pass/fail status * Vulnerability count by severity * Remediation status PCI requires quarterly clean ASV scans — Codex tracks the cadence. ### 11.4 — Internal pen tests [#114--internal-pen-tests] Annual + after-significant-change pen test reports — uploaded with: * Test date + scope * Tester identity (internal or external firm) * Findings + remediation status * Re-test results (for findings) ## Requirement 12 — Information security policy [#requirement-12--information-security-policy] Linked policy documents + annual review attestations + acknowledgment records. ## What this catalog isn't [#what-this-catalog-isnt] PCI DSS has prescriptive control parameters that vary by environment scope — Codex's evidence catalog reflects what auto-evidence can capture; specific configuration values (password length minimums, session timeout maximums, etc.) need to be set in your tooling per the PCI DSS standard. See the [PCI DSS framework guide](/codex/pci-dss) for SAQ selection and full requirement coverage. # PCI DSS (/codex/pci-dss) PCI DSS (Payment Card Industry Data Security Standard) applies to any company that stores, processes, or transmits cardholder data (CHD) — directly or indirectly through a payment processor. SaaS vendors that touch payment flows, embed Stripe Elements, or hold tokenized PANs need to satisfy at least PCI DSS Self-Assessment Questionnaire (SAQ) A or A-EP. ## Which SAQ applies to you? [#which-saq-applies-to-you] | Your situation | SAQ | Auditor scope | | ------------------------------------------------------------------------------------------ | ----------------------- | ------------------------------------------- | | You use a hosted payment page (Stripe Checkout, PayPal redirect) and never touch card data | **SAQ A** | \~22 requirements | | You embed Stripe Elements / Square SDK that posts directly to the processor | **SAQ A-EP** | \~146 requirements | | You collect card data on your own forms and tokenize it server-side | **SAQ D** | \~329 requirements (a real audit) | | You're a payment processor or service provider | **PCI DSS Level 1 RoC** | Full Report on Compliance with QSA assessor | Most SaaS startups are SAQ A or A-EP. Codex automates the SAQ A-EP path; if you're SAQ D or Level 1, you need a QSA, not just Codex. ## Requirement mapping (PCI DSS v4.0) [#requirement-mapping-pci-dss-v40] ### Requirement 1 — Install and maintain network security controls [#requirement-1--install-and-maintain-network-security-controls] | 1.x | Codex evidence | | -------------------------- | --------------------------------------------------------------- | | 1.2 — Network segmentation | AWS/GCP/Azure VPC + security group configs from cloud connector | | 1.3 — Firewall rules | Cloud security group rules + WAF config | | 1.4 — Wireless protections | Out of scope for cloud-only SaaS | ### Requirement 2 — Apply secure configurations [#requirement-2--apply-secure-configurations] | 2.x | Evidence | | --------------------------------- | ---------------------------------------------------------------------------------------- | | 2.2 — Configuration standards | Terraform/IaC commit history + drift reports from cloud connectors | | 2.3 — Default credentials changed | Cloud IAM user inventory (no root user with active access keys, no default DB passwords) | ### Requirement 3 — Protect stored account data [#requirement-3--protect-stored-account-data] | 3.x | Evidence | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 3.5 — PAN encryption at rest | Database encryption config (RDS KMS, Cloud SQL CMEK, Cosmos CMK). For SAQ A-EP, you should be tokenizing — Codex looks for direct PAN storage as a critical exception. | | 3.6 — Cryptographic key management | KMS config + key rotation history | ### Requirement 4 — Protect data in transit [#requirement-4--protect-data-in-transit] | 4.x | Evidence | | -------------------------------------------- | ------------------------------------------------------------------- | | 4.2 — Strong cryptography on public networks | TLS coverage scan (no TLS \<1.2, no weak ciphers) on every endpoint | ### Requirement 5 — Protect against malware [#requirement-5--protect-against-malware] | 5.x | Evidence | | ------------------------------------- | ----------------------------------------------------------- | | 5.2 — Anti-malware on at-risk systems | EDR coverage from CrowdStrike/SentinelOne via MDM connector | ### Requirement 6 — Develop and maintain secure systems [#requirement-6--develop-and-maintain-secure-systems] | 6.x | Evidence | | --------------------------------------- | ----------------------------------------------------------------- | | 6.2 — Bespoke software development | GitHub PR review records + branch protection + required CI | | 6.3 — Vulnerability management | Snyk/Dependabot/Wiz findings + remediation timelines per severity | | 6.4 — Public-facing web app protections | WAF config + WAF rule violations from CDN connector | ### Requirement 7 — Restrict access by business need [#requirement-7--restrict-access-by-business-need] | 7.x | Evidence | | --------------------------- | -------------------------------------------------------------------------- | | 7.2 — Access control system | IdP role-based assignments with documented business justification per role | | 7.3 — Access reviews | Quarterly access review snapshots from Codex | ### Requirement 8 — Identify users and authenticate access [#requirement-8--identify-users-and-authenticate-access] | 8.x | Evidence | | --------------------------------------- | ---------------------------------------------------- | | 8.3 — Strong authentication for non-CDE | IdP MFA enforcement reports | | 8.4 — MFA for CDE access | Conditional access policy showing MFA on CDE systems | | 8.5 — Multi-step authentication | MFA factor inventory per user | ### Requirement 9 — Restrict physical access to CHD [#requirement-9--restrict-physical-access-to-chd] For cloud-only SaaS, this devolves to "your hyperscaler handles physical security" + their AOC/AoC document linked from your evidence pack. ### Requirement 10 — Log and monitor all access [#requirement-10--log-and-monitor-all-access] | 10.x | Evidence | | -------------------- | ----------------------------------------------------------------- | | 10.2 — Audit logs | SIEM connector event coverage report | | 10.3 — Log integrity | CloudTrail / Azure Activity Log / Cloud Audit immutability config | | 10.6 — Log review | Log review activity records (who reviewed, when, finding count) | ### Requirement 11 — Test security regularly [#requirement-11--test-security-regularly] | 11.x | Evidence | | ----------------------------------- | ----------------------------------------------------------------------------- | | 11.3 — External vulnerability scans | Quarterly ASV scan reports (you upload, Codex stores with scan date + vendor) | | 11.4 — Internal pen tests | Annual pen test reports (uploaded) | ### Requirement 12 — Information security policy [#requirement-12--information-security-policy] Codex links to your published security policy + tracks annual review attestations. ## What's different about PCI DSS vs SOC 2 [#whats-different-about-pci-dss-vs-soc-2] PCI DSS is **prescriptive** where SOC 2 is **principle-based**. SOC 2 says "you should manage access" — PCI DSS says "you must enforce password length ≥ 12 characters with complexity requirements." Codex captures the prescriptive numbers and surfaces violations specifically. Things PCI is stricter about: * **Quarterly external scans by an Approved Scanning Vendor (ASV)** — mandatory, not optional * **Annual penetration testing** — mandatory after every significant change * **Specific encryption algorithms and key sizes** — Codex flags weak crypto config * **Card data masking** when displayed (last 4 only) * **Limiting CDE scope** — explicit network segmentation between CDE and non-CDE ## When you're ready [#when-youre-ready] **Reports → PCI DSS evidence package** outputs: * SAQ (correctly mapped to your scope: A, A-EP, or D) * Per-requirement implementation evidence * AoC (Attestation of Compliance) draft * Quarterly ASV scan history * Annual pen test reports * ROC (Report on Compliance) supporting evidence — for Level 1 service providers For SAQ A-EP, sign and submit to your acquirer annually. For Level 1, your QSA writes the ROC; Codex provides the underlying evidence. # SOC 1 (/codex/soc1) SOC 1 is the AICPA report focused on **internal controls over financial reporting (ICFR)** at a service organization. It's distinct from SOC 2 (security) and applies when your SaaS is part of your customers' financial reporting chain. ## Do you need SOC 1? [#do-you-need-soc-1] You probably need SOC 1 if your customers ask for it during procurement OR if any of these apply: * **Payroll processing** — your SaaS issues paychecks, W-2s, 1099s * **Billing and invoicing** — your SaaS generates invoices customers post to GL * **Payment processing** — your SaaS settles payments to customer bank accounts * **Accounting / GL automation** — your SaaS posts journal entries * **Inventory / supply chain valuation** — your SaaS assigns costs that flow into inventory accounts * **Time-and-attendance** — your SaaS produces timesheet data that drives payroll calc Pure data tools (analytics, monitoring, internal collaboration) typically don't need SOC 1. Layer doesn't need SOC 1 — Codex doesn't either. But if you sell to F500 finance teams, expect to be asked. ## SOC 1 Type I vs Type II [#soc-1-type-i-vs-type-ii] | | Type I | Type II | | ------------------- | ------------------------------------------ | --------------------------------------------------------------------- | | **What it covers** | Controls designed correctly *as of a date* | Controls operated effectively *over a period* (typically 6-12 months) | | **Customer demand** | Acceptable for first-time engagement | Required by SOX-regulated customers (almost everyone) | | **Effort** | 6-8 weeks | 6-12 months observation + 6-8 weeks audit | SOX 404 (the public-company internal-controls regime) makes Type II non-negotiable for serving public-company customers. Public customers need to rely on your SOC 1 Type II to satisfy their own SOX 404 obligations. ## SOC 1 vs SOC 2 — overlap and distinction [#soc-1-vs-soc-2--overlap-and-distinction] | | SOC 1 | SOC 2 | | ---------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Focus** | Financial reporting accuracy | Security, availability, confidentiality, processing integrity, privacy | | **Audience** | Customer's CFO + external auditor (for SOX 404 reliance) | Customer's CISO + procurement | | **Common controls** | Access management, change management, computer operations | Access management, change management, system operations | | **Differentiating controls** | Transaction processing accuracy, completeness, timing; data integrity in financial flows | Encryption, EDR, vulnerability management, incident response | There's significant overlap — about 40% of controls map directly. Codex tracks both frameworks in parallel without duplicate work. ## Codex's role for SOC 1 [#codexs-role-for-soc-1] Codex doesn't perform the audit (your CPA firm does that), but it provides the evidence the auditor will request for IT General Controls (ITGCs) — the five-question framework auditors use to evaluate the IT environment supporting your application: ### 1. Logical access (most evidence here) [#1-logical-access-most-evidence-here] | Question | Codex evidence | | --------------------------------------------- | --------------------------------------------------------------------- | | Who has access to the system? | IdP user list with last activity | | What can they do? | Per-user role + permission set | | Were users provisioned with manager approval? | Provisioning event logs with approver identity | | Are terminated users removed timely? | HRIS termination → IdP deactivation timestamp diff | | Are access reviews conducted? | Quarterly access review snapshots with reviewer + approval timestamps | ### 2. Change management [#2-change-management] | Question | Codex evidence | | ------------------------------------------- | ------------------------------------------------------------------------ | | Are code changes reviewed? | GitHub/GitLab PR review records with reviewer, comments, merge timestamp | | Are changes tested before production? | CI status records (tests passed) per merge | | Is there a separation between dev and prod? | Cloud account/project isolation evidence | | Are emergency changes documented? | Hotfix branch records + retroactive review evidence | ### 3. Computer operations [#3-computer-operations] | Question | Codex evidence | | ----------------------------------- | --------------------------------------------------- | | Are jobs scheduled and monitored? | Cron + workflow execution logs from cloud connector | | Are failures detected and resolved? | PagerDuty / on-call ticket history with MTTR | | Are backups taken and tested? | Backup snapshot history + restore-test logs | ### 4. Data integrity [#4-data-integrity] | Question | Codex evidence (largely manual at SOC 1 level) | | ----------------------------------------- | ---------------------------------------------------- | | Are interfaces between systems validated? | Mostly manual — reconciliation reports, error queues | | Are exception reports reviewed? | Linked dashboards / log queries + review records | ### 5. Information security [#5-information-security] Mirrors SOC 2 CC6/CC7 controls. Codex's SOC 2 evidence covers this. ## What auditors specifically look for in SOC 1 [#what-auditors-specifically-look-for-in-soc-1] * **Population completeness** — when the auditor samples a control (e.g. "show me 25 PR review records"), Codex's audit log must demonstrate the sample is from the complete population, not cherry-picked. * **Control owner identification** — every control needs a named owner. Codex tracks the assignee per control. * **Independent review** — controls performed by the same person who created the work being controlled don't satisfy ITGCs. Codex flags self-approving PRs and similar self-reviews as exceptions. * **Period coverage** — the Type II observation window must show every control operated continuously. Codex's continuous evidence collection makes this trivial; the gap is documented in the SOC 1 if a control was added partway through the period. ## When you're ready [#when-youre-ready] **Reports → SOC 1 evidence package** outputs: * ITGC evidence per category with timestamps * Population completeness samples (random samples auditor can verify against full data) * Exception register (controls that didn't operate; documented justification) * Bridge letter template (used between Type II audit periods to extend reliance) Most SOC 1 auditors accept Codex packages directly; some require evidence in their own portal — Codex CSV export covers that. # SOC 2 evidence catalog (/codex/soc2-evidence-catalog) This page lists the highest-traffic SOC 2 Common Criteria controls and the exact evidence Codex collects for each. Use it during audit prep to predict what your auditor will see. ## CC6 — Logical and Physical Access Controls [#cc6--logical-and-physical-access-controls] ### CC6.1 — Logical access provisioning [#cc61--logical-access-provisioning] | Source | API call | Refresh cadence | | ------------------ | ------------------------------------------------------------------------- | --------------- | | Google Workspace | `admin.directory.users.list` (filter on `creationTime` since last sync) | Every 6 hours | | Microsoft Entra ID | `/v1.0/users?$filter=createdDateTime ge {since}` | Every 6 hours | | Okta | `/api/v1/logs?filter=eventType eq "user.lifecycle.create"` | Every 6 hours | | BambooHR (HRIS) | `/api/gateway.php/{company}/v1/employees/directory` (correlate hire date) | Daily | When an HRIS connector is wired, Codex correlates the HRIS hire-date record to the IdP provisioning event so auditors see the full chain: HRIS hire → IdP provisioning → app assignments. Evidence shape per provisioning event: ```json { "user_id": "string", "email": "string", "created_at": "ISO timestamp", "created_by": "string (admin email)", "source": "google_workspace | microsoft_entra_id | okta | bamboohr_hris", "evidence_url": "deep link into the source admin console" } ``` What auditors verify: every provisioning event has a documented business reason. Codex links to the corresponding HRIS new-hire record so the chain is "HRIS hire → IdP provisioning → app assignments" with timestamps showing each step happened in the right order. ### CC6.2 — User access reviews [#cc62--user-access-reviews] Codex generates a quarterly access-review snapshot: * Per user: list of apps assigned, role within each app, last activity date * Per app: list of users with access, broken down by role * Diff vs previous review: who was added, removed, or changed roles Reviewers (typically managers) get a Codex link to approve or flag each user. The auditor sees the completed review with reviewer identity + timestamp + decisions. ### CC6.3 — Role-based access enforcement [#cc63--role-based-access-enforcement] | Source | Evidence | Refresh cadence | | ------ | ------------------------------------- | --------------- | | Okta | Per-app role assignments via SCIM | Every 6 hours | | GitHub | Org admin + team membership inventory | Every 6 hours | | Slack | Workspace admin + role inventory | Daily | Source data: * IdP role assignments per app (via SCIM or app-specific API) * Per-app admin/owner/member counts * Privileged-access reports (admin role count by app, with named users) Auditors look for: separation of duties (e.g. the same person isn't dev + ops + finance admin) and least privilege (e.g. fewer admins than members). ### CC6.6 — Logical access removal on termination [#cc66--logical-access-removal-on-termination] The control most companies fail. Codex measures the gap between HRIS termination and IdP deactivation. | Source | Evidence | Refresh cadence | | ------------------ | ------------------------------------------------------ | --------------- | | BambooHR (HRIS) | Termination event timestamp | Every 6 hours | | Rippling (HRIS) | Termination event timestamp | Every 6 hours | | Gusto (HRIS) | Termination event timestamp | Every 6 hours | | Deel (HRIS) | Termination event timestamp | Every 6 hours | | Okta | User deactivation timestamp (correlate to termination) | Every 6 hours | | Google Workspace | User suspension timestamp | Every 6 hours | | Microsoft Entra ID | `accountEnabled=false` timestamp | Every 6 hours | ```text Termination event: 2026-04-15 17:00 UTC (HRIS: BambooHR) IdP deactivation: 2026-04-15 17:08 UTC (Google Workspace) Gap: 8 minutes ✓ (under 24h SLA) ``` For an auditor, this is the killer evidence: a real timestamp diff per terminated employee proving the SLA holds. Codex also flags any termination where IdP deactivation didn't happen within 24h — those become exceptions you have to remediate before audit. ### CC6.7 — Encryption at rest [#cc67--encryption-at-rest] | Asset class | Source | Evidence | | ------------- | ------------------------------------- | ---------------------------------------------------------------------------- | | Endpoints | MDM (Jamf, Kandji, JumpCloud, Intune) | Per-device disk encryption status (FileVault for Mac, BitLocker for Windows) | | Cloud storage | AWS | S3 bucket encryption configs (SSE-S3, SSE-KMS, or SSE-C) | | Cloud storage | GCP | GCS bucket encryption config + CMEK keys | | Cloud storage | Azure | Storage account encryption + CMK config | | Databases | RDS / Cloud SQL / Cosmos DB | Per-instance encryption + KMS key reference | Codex polls these daily and flags any unencrypted resource as a material exception. ### CC6.8 — Endpoint protection [#cc68--endpoint-protection] | Source | Evidence | | ------------------------- | -------------------------------------------------------------------------- | | MDM | EDR/antivirus install status, OS patch level vs latest, screen lock policy | | CrowdStrike / SentinelOne | Per-host EDR coverage + last check-in time | ## CC7 — System Operations [#cc7--system-operations] ### CC7.1 — Vulnerability management [#cc71--vulnerability-management] Illustrative example — synthetic data; CVE-0000-0000 is a placeholder. ```text Vulnerability discovered: 2026-04-12 (GitHub Dependabot) Severity: High (CVE-0000-0000) Affected repo: api-gateway First triaged: 2026-04-12 (PR #2143 opened) Resolved: 2026-04-13 (PR merged + deployed) SLA window: <30 days for High ✓ ``` Codex tracks: * All findings from Snyk, Wiz, CrowdStrike, Dependabot, GHAS * Time to triage + time to remediate per severity * SLA compliance rates (% of High findings resolved within 30d, etc.) ### CC7.2 — Security event detection [#cc72--security-event-detection] Source data: SIEM connector events (Datadog, Splunk, Sumo, New Relic). Codex pulls: * Event volume per category (auth failures, anomalous logins, privilege escalations) * Alert rules configured + last fired * Coverage gaps (event sources NOT being collected) ### CC7.3 — Incident response [#cc73--incident-response] Per-incident evidence: ```text Incident: PagerDuty #INC-2025-1234 Severity: SEV-2 Detected: 2026-04-15 03:14 UTC (alert: api-gateway p99 latency > 5s) Acknowledged: 2026-04-15 03:16 UTC (oncall: alice@axiomancer.io) Resolved: 2026-04-15 04:42 UTC Post-mortem: linked to Notion page (auto-detected via incident note) ``` ### CC7.4 — Recovery from incidents [#cc74--recovery-from-incidents] | Source | Evidence | | ---------- | -------------------------------------------------------------------------------- | | AWS Backup | Snapshot history per resource (RDS, EBS, EFS), retention config | | GCP | Cloud Storage versioning + Cloud SQL backups | | Azure | Recovery Services Vault snapshots | | Manual | Restore-test results (you upload, Codex stores with timestamp + tester identity) | Auditors specifically want to see **restore tests**. Codex sends quarterly reminders to your backup owner to test a restore and upload the result. ## CC8 — Change Management [#cc8--change-management] ### CC8.1 — Change authorization [#cc81--change-authorization] ```text PR #2143 (api-gateway) Author: bob@axiomancer.io Reviewers: alice@axiomancer.io (approved), charlie@axiomancer.io (approved) Merged: 2026-04-13 14:32 UTC Required reviewers: 2 ✓ Branch protection: enforced on main ✓ ``` Codex pulls every merged PR from connected code hosts (GitHub, GitLab) and verifies: * Required reviewers met * Branch protection rules enforced (no direct pushes to main) * CI passed before merge ## What this catalog isn't [#what-this-catalog-isnt] This isn't the complete list — it's the controls that drive 80% of audit attention. Other CC controls (CC1-5 governance, CC9 risk mitigation) are mostly policy + process, not auto-evidenceable. See the [SOC 2 framework guide](/codex/soc2) for the full mapping. # SOC 2 (/codex/soc2) SOC 2 audits 5 Trust Service Criteria — Security (mandatory), Availability, Confidentiality, Processing Integrity, and Privacy. Most companies start with Security only (the "Common Criteria") and add others when customers demand them. ## Type I vs Type II [#type-i-vs-type-ii] | | Type I | Type II | | ------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- | | **What it proves** | Controls are designed correctly *as of a point in time* | Controls operated effectively *over a period* (typically 6-12 months) | | **Audit timeline** | 4-8 weeks | 6-12 months observation window + 4-8 weeks audit | | **Customer demand** | Acceptable for first-time vendors | Required by most enterprise procurement | | **Codex effort** | A few weeks of setup | Same setup, then continuous monitoring during the observation window | **Recommendation:** if you've never had a SOC 2, start with Type I to validate your controls work, then immediately begin a Type II observation window. Most companies run Type II annually thereafter. ## How Codex maps the Common Criteria (CC) controls [#how-codex-maps-the-common-criteria-cc-controls] The 2017 (TSC 2017) and 2022 update (Trust Services Criteria 2017 — Revised May 2022) define \~60 Common Criteria controls. Codex auto-evidences the majority: ### CC6 — Logical and Physical Access Controls (the heavy lifting) [#cc6--logical-and-physical-access-controls-the-heavy-lifting] | Control | Evidence Codex pulls | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **CC6.1** — Logical access provisioning | IdP user creation logs (Google Workspace, Okta, Entra ID), MDM device assignment records | | **CC6.2** — User access review | Quarterly diff of who has access to what, exported from IdP + per-app assignments | | **CC6.3** — Role-based access | App-level role assignments from connected SaaS (Slack admin role, GitHub team membership, etc.) | | **CC6.6** — Logical access removal on termination | HRIS termination event → IdP deactivation timestamp diff (proves \<24h SLA) | | **CC6.7** — Encryption at rest | MDM disk encryption status (FileVault for Mac, BitLocker for Windows), cloud-storage encryption config | | **CC6.8** — Endpoint protection | MDM-reported antivirus/EDR status, OS patch level, screen lock policy | ### CC7 — System Operations [#cc7--system-operations] | Control | Evidence | | ------------------------------------ | -------------------------------------------------------------------------------------------------- | | **CC7.1** — Vulnerability management | GitHub Dependabot alerts + Snyk/Wiz/CrowdStrike findings + remediation timelines | | **CC7.2** — Security event detection | SIEM connector events (Datadog, Splunk, Sumo Logic), suspicious-login alerts from IdP | | **CC7.3** — Incident response | Incident tickets from PagerDuty/Linear/Jira with start/end timestamps, severity, post-mortem links | | **CC7.4** — Recovery from incidents | Backup snapshots from cloud connectors (AWS Backup, GCP, Azure), restore-test logs | ### CC8 — Change Management [#cc8--change-management] | Control | Evidence | | -------------------------------- | ---------------------------------------------------------------------- | | **CC8.1** — Change authorization | GitHub/GitLab PR review records + approver identity + merge timestamps | ### CC1-CC5 — Governance, risk assessment, communication [#cc1-cc5--governance-risk-assessment-communication] These are mostly **policy + training + role definitions** — Codex links to your Notion/Confluence pages and tracks training completion via the LMS connector. ## What Codex can't auto-evidence (you assign humans) [#what-codex-cant-auto-evidence-you-assign-humans] * **CC1.1** — Code of conduct: link to your published code of conduct * **CC2.2** — Internal/external communication: link to your security page + customer comms templates * **CC3.1** — Risk identification process: link to your risk register and quarterly review minutes * **CC9** — Risk mitigation: vendor due diligence questionnaires (Codex stores them; humans complete them) * **A1.1** — Availability commitments: SLAs and uptime monitoring contracts ## Recommended setup order [#recommended-setup-order] 1. **Day 1**: Sign up, pick SOC 2 (Common Criteria), connect Google Workspace or M365 (covers \~30% of CC6 controls instantly) 2. **Day 1-3**: Connect MDM (Jamf/Kandji/Intune). Covers CC6.7, CC6.8 — disk encryption, endpoint protection. \~20% more. 3. **Day 3-7**: Connect GitHub or GitLab. Covers CC8.1 (change management). \~10% more. 4. **Week 2**: Connect ticketing (Jira/Linear) and on-call (PagerDuty). Covers CC7.3, CC7.4. \~15% more. 5. **Week 2**: Connect cloud (AWS/GCP/Azure). Covers CC7.1 partial (infrastructure CVEs), CC6.7 cloud encryption. \~10% more. 6. **Week 3-4**: Assign humans to the remaining 15-20% (policy, risk, training, vendor mgmt). After \~4 weeks of focused setup, \~80-85% of CC controls are auto-evidenced and continuously monitored. The remaining 15-20% are humans-required workflows tracked in Codex. ## When you're ready for the auditor [#when-youre-ready-for-the-auditor] **Reports → SOC 2 evidence package** generates a single PDF + folder of CSVs with: * Every CC control, status, evidence sources, last-verified timestamp * Per-control evidence snapshots (with API call timestamps) * Exception list (controls marked "exception" with documented justification) * Ownership matrix (who is responsible for each non-auto-evidenced control) Hand to your auditor. Most accept Codex packages with no follow-up. # The decision cycle (/invest/decision-cycle) ## One cycle, end to end [#one-cycle-end-to-end] Invest's decision loop is heartbeat-driven, and every order it can produce is a paper order. Each cycle runs the same stages under a shared wall-clock budget, designed so that late results are discarded before they can produce side effects. The budget is shared across the cycle, with a per-candidate start floor and a re-entrancy guard so cycles do not pile into each other. A wedged cycle is force-retired after its budget plus a grace period expires. Restart safety is part of the same design: execution state persists in a Redis cache, and at boot the system reconciles against broker truth. Entry authority is refused until the broker-versus-cache position comparator matches. ## One agent, two terminal answers [#one-agent-two-terminal-answers] The sole order proposer is a PydanticAI-based decision agent with eighteen registered tools, and its terminal authority is narrow: propose an order or a hedge, or return no\_action. It cannot approve, size past the gate, or submit. The tools give it a research surface over its own world: option chains and greeks, intraday bars, portfolio state, buying power and pattern day trader status, the market calendar, signal queries, historical replay and event studies, concentration checks, chain resolution, price structure, and stale-cache awareness. ## No fallback chain [#no-fallback-chain] Model calls route through an OpenAI-compatible LiteLLM proxy. The primary model is pinned and there is no automatic fallback chain: on provider failure the system retries the same lane, then fails closed to no\_action. An optional smart-escalation mode allows a second pass within the same model family with its own tool budget, and a panel or consensus-jury mode is observe-only and disabled unless explicitly configured. An optional ranked-batch mode can ask for several ranked convictions instead of one, but it defaults to off, and its deterministic per-intent selector is fail-safe off and instrument-only by design. That selector is the keystone the system is still working to meet, and these docs describe the intended target rather than a completed claim. ## Every decision leaves one record [#every-decision-leaves-one-record] Each decision writes a durable decision\_log row carrying the gate result and the submission outcome on the same row, so a proposal, its verdict, and its fate can be reviewed together. Rows ending in no\_action are server-stamped as operational (something infrastructure-side prevented a decision) or market\_judgment (the model declined on the merits). The split keeps "the system did nothing" interpretable after the fact, without reading health into any single flag. This is also the record the operator console's decision-quality and execution-quality panels review, so the cycle and the console are reading from the same durable source rather than from two reconstructed views. The gate in stage three is the fail-closed validator described in [risk controls](/invest/risk-controls); its implemented form is covered in [risk in practice](/invest/risk-in-practice). # Evidence feeds (/invest/evidence-feeds) ## Evidence arrives before decisions do [#evidence-arrives-before-decisions-do] Invest is a private-preview paper-trading research system, and its decision loop is only as good as what it reads. Before the agent considers a candidate, a fleet of signal publishers gathers market structure, options flow, disclosed activity, and policy events, then writes the results into shared Postgres and Redis state that the decision cycle reads from. Fourteen publisher services make up the fleet. Some watch market microstructure: gex, darkpool prints from Polygon's TRF feed, and options flow. Others follow disclosed activity: congressional trading from Unusual Whales, insider Form 4 filings pulled from SEC EDGAR full-text search, and Schedule 13D activism filings from the same source. A macro pair tracks regime conditions from CBOE VIX and FRED data alongside anomaly indicators. A policy pair watches official government channels (White House, Federal Reserve, EIA, USTR, SEC, and the Federal Register) plus policy-shock posts from Truth Social. One legacy screener publisher is retired, and the ThetaData poll and stream flows run display-only. Raw market data follows a documented hierarchy. ThetaData is primary for options chains and greeks, Polygon is primary for real-time stocks, Yahoo fills gaps in stock data, and Interactive Brokers is the fallback. ThetaData's stock endpoints return errors by design because the subscription is options-only, and the system treats those errors as expected rather than as faults. ## Collection is not admission [#collection-is-not-admission] A signal being collected does not mean it is trusted. A signal-source policy file decides which feeds may reach the decision agent, and a source missing from the policy fails closed. Absence is not treated as admission by default. The admitted set is deliberately small: gex, net premium flow, darkpool flow, policy shock, congressional trading from Unusual Whales, insider Form 4 and insider velocity signals, and anomaly regime. Even inside that set, authority is limited. gex enters as a conditioner only and never yields candidates of its own. Everything else stays observational. Market regime, activism, and several research feeds are blocked from candidate generation. Six Unusual Whales Kafka families are ingested observe-only and never feed decisions. Display-only feeds can appear on operator surfaces without reaching the agent. ## Freshness and cost are enforced [#freshness-and-cost-are-enforced] Stale evidence is treated like missing evidence. A freshness watchdog tracks each source's newest published timestamp and pages when a source goes quiet, applying NYSE-calendar market-hours logic so an overnight silence on a trading day is weighed differently from a weekend. Each source also runs under a cost budget, and budget enforcement fails closed when cost recording is disabled: a source whose spend cannot be accounted for stops contributing. ## Unregistered sources cannot write at all [#unregistered-sources-cannot-write-at-all] Publisher writes pass through Postgres row-level security. A source that is not registered is rejected at the database itself with a permission error, before application logic ever sees the row. The admission policy decides what the agent may read; row-level security decides what may exist in the first place. ## Next reading [#next-reading] See how the agent consumes this evidence inside a single cycle. See what the agent may propose once it has read the evidence. # Invest orientation (/invest/getting-started) ## Start with the boundary [#start-with-the-boundary] Invest is a private-preview autonomous research and execution system for US options and equities **paper trading only**. It is not investment advice, the current preview does not place live orders, and there is no public self-serve signup or product API today. This documentation explains the system's intended behavior and controls. It is not a recommendation to buy, sell, or hold any security or strategy.

Invest paper-trading portfolio overview showing net liquidation, daily P and L, open options positions, and risk-limit utilization

## Read the system in order [#read-the-system-in-order] ### Begin with evidence [#begin-with-evidence] Market context and portfolio state establish the evidence available to the research loop. Freshness and position truth are conditions of safe evaluation, not after-the-fact checks. ### Separate generation from selection [#separate-generation-from-selection] An LLM produces high-recall candidates. Deterministic selection and validation decide which, if any, can continue. The LLM does not approve an order. ### Require a fail-closed gate [#require-a-fail-closed-gate] A candidate must satisfy risk and feasibility controls before an Interactive Brokers paper order can be approved. Missing, stale, or contradictory evidence prevents entry. ### Keep monitoring after entry [#keep-monitoring-after-entry] An approved paper order enters lifecycle monitoring. Controls continue to govern state, and exits remain available even while entry blocks are active. ## Next reading [#next-reading] Trace the evidence, candidate, selection, gate, order, and monitoring flow. Review the conceptual controls that protect paper execution. # How Invest works (/invest/how-it-works) ## From evidence to paper order [#from-evidence-to-paper-order] Invest turns market and portfolio evidence into a constrained paper-trading decision. It uses Python and NautilusTrader for the trading system, with Interactive Brokers Gateway/TWS API connectivity for paper execution. Options research draws on ThetaData; stock research uses Polygon with Yahoo gap-fill when needed. ## Responsibilities by stage [#responsibilities-by-stage] Provide market and portfolio context with enough freshness and consistency to evaluate a candidate. Use the LLM to propose a broad set of research candidates. Generation increases recall; it is not an approval mechanism. Deterministically compare candidates against defined constraints, normalize the proposal, and reject incomplete or incompatible inputs. Fail closed unless a candidate is feasible and within controls. Only an approved candidate can reach an Interactive Brokers paper order. ## A system designed to break loops [#a-system-designed-to-break-loops] The intended control model makes the deterministic selector the authority that decides and breaks loops. That role is still being proven load-bearing. Invest therefore treats uncertain evidence, failed validation, and unproven control behavior as reasons to withhold an entry rather than as signals to continue. Paper execution is an operational test boundary, not a claim that autonomous trading is safe or complete. The system does not provide investment advice. # Invest (/invest) Invest is in private preview and operates in **paper trading only**. It is not investment advice. There is no public self-serve signup or product API today. Start with the paper-trading boundary, evidence posture, and current availability. Follow the evidence-to-order lifecycle and the deterministic gates between each stage. Learn the conceptual controls that keep paper execution fail-closed. Understand the research posture, candidate generation, and validation boundary. ## The decision path [#the-decision-path] ## What Invest is proving [#what-invest-is-proving] The north star is clear: the LLM expands the research frontier, while a deterministic selector decides and breaks loops. That selector is still being proven load-bearing; these docs describe the intended operating model, not a completed claim. An approved entry does not remove the need for ongoing control. Exit paths remain available even when new entries are blocked. Invest changes land weekly during the preview. Follow them in the [changelog](/changelog). # Operator console (/invest/operator-console) ## Watching a system that trades on its own [#watching-a-system-that-trades-on-its-own] Invest runs unattended, but it is not unobserved. A Next.js operator console fronts a Python backend and gives the operator a live view of the paper book and the controls that bound it. This is operator tooling for a private-preview system: there is no public signup and no self-serve access, and nothing here changes the fact that Invest places paper orders only. The console is deliberately split into two exposure tiers. The full console, with its write capability, lives on a private network. A separate read-only viewer is exposed through a Basic-Auth Cloudflare Tunnel for people who should see state without being able to change it. Both tiers look at the same underlying system; they differ only in whether the person looking can act. None of this widens access to Invest itself, which remains a private-preview system with no public signup and no product API. ## What the panels show [#what-the-panels-show] The console groups its surface into panels: a kill switch, portfolio risk, strategy health, model comparison, decision quality, execution quality, and an approval queue. Alongside them, charts render options flow, the volatility surface and skew, payoff diagrams, Greek curves, and a risk heatmap. The approval queue pairs with escalation routes that can approve, reject, close a position, or disable a signal source, so a human decision has somewhere to land when the system asks for one. ## One audited path for every knob change [#one-audited-path-for-every-knob-change] Knob mutations do not write to Redis directly. Every change flows through a single pipeline: a confirm modal collects a reason and, for destructive knobs, a typed confirmation; destructive actions such as panic\_flatten additionally require a one-shot nonce; the request then passes an allowlist and a bounds check; and finally the Redis write and the Postgres audit row commit together in one transaction. If any stage fails, nothing is applied and nothing is half-recorded. Operator identity rides an X-Operator header that an environment allowlist gates. The console therefore knows who is acting, and the audit trail ties each mutation to that identity, the reason they gave, and the value that was applied. ## Alerts and writes beyond the browser [#alerts-and-writes-beyond-the-browser] A Telegram operations bot mirrors alerts and heartbeats so the operator does not have to sit in the console to notice something. It also supports selected knob writes, such as adjusting heat, and it displays the clamped value that actually took effect rather than only the value that was requested. The bot is a narrow front end over the same audited pipeline, not a side door around it. For the controls the console exposes, see [risk in practice](/invest/risk-in-practice). For the decision record the panels review, see [the decision cycle](/invest/decision-cycle). # Risk controls (/invest/risk-controls) ## Fail closed before entry [#fail-closed-before-entry] Invest is designed so that a candidate that cannot be supported by current, internally consistent evidence does not become a new paper entry. Risk controls are a decision boundary, not a reporting layer. ## Control areas [#control-areas] Check whether the proposed structure is feasible within paper buying power and its required order conditions before it can be submitted. Evaluate aggregate options exposure and concentration so an otherwise valid candidate does not create an unsuitable combined posture. Constrain position size and modeled maximum loss according to the system's defined risk envelope. Require current, reconcilable market and portfolio state. Stale or conflicting state blocks a new entry. ## Portfolio-level protections [#portfolio-level-protections] Invest's design separates always-on entry safety checks from broader emergency and equity-protection mechanisms. Some portfolio protections are profile-dependent in the current paper phase, so their presence in the design does not imply that every conceptual control actively blocks every paper entry. Entry blocks do not remove exit availability for existing paper positions; lifecycle monitoring continues to preserve the ability to reduce or close exposure. These controls are described at a conceptual level because Invest is private preview. Their presence is not a guarantee of performance, safety, or investment suitability. # Risk in practice (/invest/risk-in-practice) ## The companion to risk controls [#the-companion-to-risk-controls] [Risk controls](/invest/risk-controls) describes what Invest's controls are for. This page describes how they are built, at the level the private-preview paper system implements them. The boundary is unchanged: paper trading only, and nothing here is investment advice. ## Two ruin fences keyed to equity [#two-ruin-fences-keyed-to-equity] The centerpieces are two equity-relative ruin fences that compare a trade's planned maximum loss against net liquidation. The per-trade ceiling is set at 25% of equity in the owner model, defaults to armed, and is designed tighten-only: the environment may lower it, and there is no disarm path. The aggregate fence caps the gross sum of planned losses at 100% of equity, and it fails closed when the book cannot be priced. An unpriceable position is treated as risk the system does not get to carry. Immediately before native order construction, a final-submit backstop re-checks planned risk post-sizing. Its job is to catch drift between sizing and submission. It exempts exposure-reducing intents: close, roll, hedge, and flatten are never blocked by a fence whose purpose is limiting new exposure. ## Portfolio breakers and the paper profile [#portfolio-breakers-and-the-paper-profile] Daily-loss and drawdown-from-peak breakers resolve from the trading profile knob and are physically matched against the Interactive Brokers mode and port agreement. The paper profile relaxes capacity and exposure caps relative to a live one but keeps the quality and feasibility checks. Operator knobs live in Redis and fail closed when absent or malformed: an absent kill switch blocks, absent heat means no sizing, and the trading profile must match the broker mode. ## Sizing ignores confidence [#sizing-ignores-confidence] Sizing is deterministic: bankroll scaled by the edge-to-loss ratio, a Kelly fraction, and a heat factor, then re-expressed on a buying-power basis. It deliberately does not read the grader's confidence in the proposal. That separation is pinned as a design invariant: the model's certainty may influence whether a proposal exists, never how large it becomes. Rejections from the evaluate\_trade validator carry explicit codes (kill switch, liquidity breach, undefined risk, insufficient buying power, aggregate and per-trade risk breaches, macro event pause, unknown strategy, options level), so a blocked entry is always explainable. ## Armed and shadow, stated plainly [#armed-and-shadow-stated-plainly] Several named controls are shadow-first by design: they observe and record rather than veto. The regime gate, the concentration gate, and the loop breaker run this way, and the console is designed to refuse setting the loop breaker to enforce. The deployment governor is documented in shadow terms as well. Treat these as instrumentation on the way to enforcement, not as enforcement. Exits get different treatment from entries. Before each automated close leg, a lifecycle ruin-fence backstop blocks only legs that would increase unbounded upside exposure, and evidence-availability failures fail open by design so a position is never trapped by a missing feed. At fill time, a naked-short guard re-checks net exposure per underlying. And when everything else is in question, the process stop remains the only fully verified emergency stop: kill-switch enforcement reads an in-process snapshot, so stopping the process is the definitive halt. Implemented controls are still paper-phase controls. Their presence is not a guarantee of safety, performance, or suitability for live trading, and Invest makes no claim of readiness for real money. ## Next reading [#next-reading] The conceptual framing these implementations serve. Where the gate sits in the cycle these controls protect. Where operators watch these controls and intervene. # Strategy and research (/invest/strategy-and-research) ## Research is broad; decisions are constrained [#research-is-broad-decisions-are-constrained] Invest uses an LLM as a high-recall candidate generator across US options and equities research. The generator may surface possibilities worth examining, but it does not select positions, validate structures, or approve orders. Those responsibilities belong to deterministic systems. ## Research principles [#research-principles] * **Evidence first** — a candidate must be grounded in available market and portfolio context, not treated as a standalone prediction. * **High recall, bounded authority** — broad generation can improve coverage, but generation is never a substitute for deterministic selection. * **Explicit uncertainty** — missing, stale, or contradictory inputs are reasons to defer or reject a candidate. * **Lifecycle learning without self-authorization** — monitoring can inform future research while controls remain responsible for deciding whether a new entry is allowed. ## What is still being proven [#what-is-still-being-proven] The system's north star is for deterministic selection to decide and break loops around LLM generation. That selector is still being proven load-bearing. Invest does not represent the current research loop as finished, reliable for live trading, or suitable as investment advice. For the decision boundary behind the research loop, see [how Invest works](/invest/how-it-works). For the controls that can block an entry, see [risk controls](/invest/risk-controls). # Strategy menu (/invest/strategy-menu) ## A menu, not an open field [#a-menu-not-an-open-field] The decision agent does not invent structures freely. It selects from a menu of 44 strategy templates that spans the option and equity structures Invest is built to express: verticals, iron condors and iron butterflies (including long and unbalanced variants), calendars, diagonals, jade lizards, backspreads, straddles and strangles in both long and short form, butterflies, covered, married, and protective equity combos, synthetics, the wheel, long box, single long and short options, and long equity. The menu is a constraint, not a suggestion. If the model proposes something off-menu, or proposes selling upside that the menu does not sanction, the proposal is downgraded to no\_action after output. The check runs after the model has spoken, not as a filter on what it may consider, so generation stays broad while the set of things that can actually become an order stays fixed. Being menu-valid is necessary but not sufficient. A candidate still has to survive deterministic selection, validation, and the fail-closed risk gate before it can reach a paper order. The menu defines the shapes Invest knows how to express; the controls decide whether expressing one is acceptable right now. ## Mixed combos are excluded from generation [#mixed-combos-are-excluded-from-generation] Nine mixed stock-and-option combos are excluded from generation everywhere: conversion, covered\_call, covered\_put, married\_put, protective\_call, protective\_collar, reversal, short\_collar, and wheel. The reason is mechanical, not strategic. The order factory cannot route non-option legs, so these structures cannot be expressed as a clean order today. This is a phase-1 guard with a documented escape hatch for re-enabling mixed-combo generation later; until that hatch is deliberately opened, the exclusion is the honest state. Several of these names also appear as templates, which means the template exists while generation of it remains switched off. ## Multi-leg means one order [#multi-leg-means-one-order] When a strategy has multiple legs, Invest submits it as one native Interactive Brokers combo (BAG) order, or not at all. There is no path that legs into a spread one side at a time, because a partially filled spread is an unintended naked position. Degenerate combos, such as a zero-width vertical, are terminally rejected with a "degenerate combo" reason rather than repaired or retried. Option orders route through SmartRouting with the exchange set to SMART. ## A deterministic enumerator alongside the model [#a-deterministic-enumerator-alongside-the-model] Alongside LLM generation, Invest includes a deterministic structure enumerator that can lay out candidate structures mechanically. Both paths feed the same selection and validation downstream, and neither one approves its own output. That separation matters for the same reason it matters everywhere in Invest: the deterministic selector is the intended authority, and it is still being proven load-bearing. For the research posture behind candidate generation, see [strategy and research](/invest/strategy-and-research). For the controls that can stop a menu-valid candidate anyway, see [risk controls](/invest/risk-controls). # Access reviews (/layer/access-reviews) Access reviews help you verify that the right people have the right access — and that nobody retains permissions they no longer need. Layer supports both scheduled review campaigns and cost-based approval rules for new access requests. ## Approval rules [#approval-rules] Approval rules define who must approve a new access request based on its estimated monthly cost. You configure rules in **Settings → Access approval rules**. ### How rules work [#how-rules-work] Each rule specifies: * **A cost range** — a minimum and optional maximum monthly cost. * **Required approval stages** — one or more of: Manager, IT, Security, or Finance. * **Priority** — when multiple rules match, all matching stages are combined into a single approval chain. When someone requests access to a tool, Layer evaluates the request's estimated monthly cost against all active rules. Every stage required by any matching rule is added to the approval chain, and stages always execute in a fixed order: 1. **Manager** approval 2. **IT** approval 3. **Security** approval 4. **Finance** approval If no rules match a request, Layer defaults to requiring IT approval. Every required stage must sign off before Layer creates the access grant — this applies to approvals made from the Slack notification **and** from the web approval view in the dashboard. A single admin click on the web path no longer short-circuits the chain; each stage is recorded independently and the grant is issued only once the last pending stage is approved. If any stage rejects, the request is rejected and no grant is created. ### Create an approval rule [#create-an-approval-rule] ### Open approval rules [#open-approval-rules] Go to **Settings → Access approval rules** in your Layer dashboard. ### Add a rule [#add-a-rule] Click **Add rule** and configure: * **Name** — a descriptive label (e.g. "High-value requests"). * **Minimum monthly cost** — the lower bound of the cost range. * **Maximum monthly cost** — the upper bound, or leave blank for no cap. * **Required stages** — toggle on the approval stages this rule requires. * **Priority** — a number to control rule ordering in the list. ### Save [#save] Click **Save**. The rule takes effect immediately for new requests. ### Example [#example] | Rule | Cost range | Stages required | | ---------- | ----------- | ------------------------------ | | Low-value | $0–$50/mo | Manager | | Mid-value | $50–$500/mo | Manager, IT | | High-value | $500+/mo | Manager, IT, Security, Finance | A request for a $200/month tool matches the mid-value rule, so it requires both manager and IT approval. ## Assigned stage approvers [#assigned-stage-approvers] By default, any admin in your organization can approve any stage of an access request. If you need tighter separation of duties — for example, only the head of finance may sign off on the Finance stage — you can assign specific people to a stage. Once a stage has one or more assigned approvers, only those users can approve or reject that stage; other admins are blocked from that stage until the assignment is removed. Stages without any assigned approvers stay open to any admin. Self-approval is always blocked: the requester cannot approve their own request even if they are assigned to a stage. ### Assign approvers to a stage [#assign-approvers-to-a-stage] ### Open stage approvers [#open-stage-approvers] Go to **Settings → Access approval rules** and open the **Stage approvers** panel. ### Assign users [#assign-users] Pick a stage (Manager, IT, Security, or Finance) and add one or more organization members. If a member has a linked Slack user, their Slack ID is stored alongside so approvals from either surface are recognized. ### Save [#save-1] Assignments take effect on the next request. Existing in-flight requests continue against their captured approval plan. ### Manage assignments via the API [#manage-assignments-via-the-api] Admin users can also manage stage approvers through the `/api/access/stage-approvers` endpoint. All routes require an admin session and are scoped to the caller's organization. List every stage approver assignment in your organization, ordered by stage. ```json Response { "approvers": [ { "id": "…", "org_id": "…", "stage": "finance", "user_id": "…", "slack_user_id": "U123ABC", "created_at": "2026-06-24T17:15:10.000Z" } ] } ``` Assign a user to a stage. `stage` must be one of `manager`, `finance`, `it`, or `security`. `slack_user_id` is optional and lets the same person approve from Slack. ```json Body { "stage": "finance", "user_id": "…", "slack_user_id": "U123ABC" } ``` Returns `201` with the created assignment. Remove an assignment by its `id`. Once the last assignment for a stage is deleted, the stage falls back to being approvable by any admin. ## Access grants [#access-grants] When a request is approved, Layer creates an access grant. Grants can be: * **Permanent** — no expiration. * **Temporary** — expires after a set duration (1 to 168 hours). If no duration is specified, temporary grants default to 24 hours. Expired temporary grants are automatically revoked. ## Review campaigns [#review-campaigns] Review campaigns let you audit existing access on a regular cadence. You can run campaigns ad-hoc or on a quarterly or annual schedule. ### Create a campaign [#create-a-campaign] When you create a review campaign, you configure: * **Scope** — which identities and applications to include. * **Reviewer strategy** — how reviewers are assigned: * **Explicit** — you manually assign reviewers. * **App owner** — the designated owner of each application reviews access. * **Manager** — each user's manager reviews their access. * **Deadline** — days until the review is due (1–365 days, default 7). * **Escalation** — days after the deadline before escalation triggers (1–90 days, default 3). ### Review lifecycle [#review-lifecycle] Each review in a campaign moves through these states: | Status | Meaning | | ------------- | ----------------------------------------- | | **Pending** | Awaiting reviewer action | | **Completed** | Reviewer confirmed or revoked access | | **Expired** | Deadline passed without action | | **Overdue** | Past deadline but still pending | | **Escalated** | Escalation triggered after overdue period | Campaign dashboards show real-time completion percentages, overdue counts, and escalation status so you can track progress. ### Export results [#export-results] You can export review results for compliance reporting. Exports include all review decisions, reviewer identities, timestamps, and any notes. Use this for SOC 2 evidence or internal audit documentation. # AI usage tracking (/layer/ai-usage-tracking) AI usage tracking gives you a single view of what your organization spends on AI tools — across OpenAI, Anthropic, GitHub Copilot, Cursor, Google Gemini, Perplexity, and RouteShift. Layer pulls usage data directly from each provider's admin API and rolls it up by person, department, and provider so you can spot waste, justify renewals, and forecast budgets. AI usage tracking is available on the **Scale** plan. See [Plans and billing](/layer/billing) for details. ## Supported providers [#supported-providers] | Provider | Source | Data collected | | ------------------ | --------- | ----------------------------------------------------------- | | **OpenAI** | Admin API | Tokens (input/output), cost per model, per-user attribution | | **Anthropic** | Admin API | Tokens (input/output), cost per model, per-user attribution | | **GitHub Copilot** | Admin API | Seat assignment and usage | | **Cursor** | Admin API | Token usage and cost per user | | **Google Gemini** | Admin API | Token usage and cost per user | | **Perplexity** | Admin API | Token usage and cost per user | | **RouteShift** | Admin API | Token usage and cost per user | Layer syncs usage data automatically once you connect a provider integration. Each record is keyed by organization, user, tool, source, month, and model — so you never lose granularity. ## View AI spend [#view-ai-spend] Open **AI Usage** in the Layer sidebar (between **Hardware** and **Renewals**) for the dedicated AI cost view. The page shows: * **Per-person spend** — every user ranked by total monthly cost, with a breakdown by tool and model. * **Department ROI** — total spend, active users, licensed seats, adoption rate, and cost per active user for each department. * **Provider ROI** — the same metrics grouped by AI provider instead of department. * **Three-month trend** — month-over-month cost and active-user changes so you can see whether spend is growing or stabilizing. The provider ROI and per-person breakdowns also surface inside the **Apps** page so you can see AI spend in context with the rest of your SaaS portfolio. ## RouteShift integration [#routeshift-integration] [RouteShift](https://routeshift.io) is the LLM proxy gateway behind Layer's AI cost tracking. When you mint a RouteShift API key per identity, every prompt, completion, and tool call is attributed to the employee who made it — so per-employee spend rolls up cleanly even across BYOK and credit-funded usage. From the **AI Usage** page, use **Open RouteShift** to jump into the RouteShift dashboard for: * Smart routing and savings — RouteShift picks the cheapest provider that meets your latency and quality bar. * Live analytics — cache hit rate, p95 latency, error rate, and savings reporting on daily, weekly, or 24-hour windows. * Per-employee key management and billing. ### RouteShift plans [#routeshift-plans] RouteShift has a single paid plan: Stripe bills **3% of measured savings** through metered billing, plus a **3% markup on credits purchases**. There are no fixed Starter, Growth, or Enterprise tiers. See [RouteShift billing](/routeshift/billing) for the current pricing model. Per-employee spend roll-up is available directly in Layer. Manage RouteShift keys, live analytics, and RouteShift billing in the RouteShift dashboard via the **Open RouteShift** link on the **AI Usage** page. ## How costs are calculated [#how-costs-are-calculated] Layer stores costs in **microcents** (1/10,000th of a cent) to avoid rounding errors across high-volume token usage. When you see dollar amounts in the dashboard, they've been converted from microcents. Each provider adapter maps the provider's native usage format to a standard record: * **Input and output tokens** are tracked separately. * **Model name** is preserved so you can compare cost across models (e.g. GPT-4o vs. GPT-4o-mini). * **Usage month** groups records into calendar months (UTC). ## Adoption metrics [#adoption-metrics] Layer calculates two key adoption metrics for every department and provider: * **Adoption rate** — the percentage of licensed seats that are actively using the tool. A low adoption rate may indicate unused seats you can reclaim. * **Cost per active user** — total monthly spend divided by the number of users who actually generated usage. Use this to benchmark whether a tool delivers value relative to its cost. ## Seat detection [#seat-detection] Layer identifies unique seats by extracting provider-specific email addresses or user IDs from usage metadata. For example, a Cursor user is identified by their `cursor_user_email`, while an OpenAI user is identified by their `openai_user_id`. This means Layer can count licensed seats even when users have different identifiers across providers. Connect your identity provider (Google Workspace, Microsoft 365, or Okta) first. Layer uses identity data to map AI usage records to employees and departments automatically. # Asset bundles (/layer/asset-bundles) Asset bundles are reusable hardware-allocation kits. A bundle describes the equipment a person should receive, then Layer matches that request against the serialized devices that are currently available in your inventory. A bundle never creates synthetic assets. Every successful allocation points to an existing device in [Asset inventory](/layer/asset-inventory). Use bundles when: * New hires in the same role receive a repeatable hardware kit. * IT needs to see shortages before promising equipment. * An admin wants to review or override the exact devices selected for a person. * A required device is unavailable and the allocation should remain visibly incomplete. ## Before you start [#before-you-start] You need: * An organization-admin account. * The recipient in your Layer workspace. * Serialized hardware records in an available state. * Enough inventory to satisfy the kit, or a plan for any reported shortages. ## Create a bundle [#create-a-bundle] ### Open asset bundles [#open-asset-bundles] Go to **Assets → Bundles** in the Layer dashboard. ### Describe the kit [#describe-the-kit] Create a bundle with a clear role or workflow name, such as “Engineering laptop kit.” Add the hardware requirements that should be matched during allocation. ### Mark required and optional items [#mark-required-and-optional-items] Required items determine whether the kit is ready to complete. Optional items can be reported as shortages without hiding the rest of the available allocation. ### Save the reusable definition [#save-the-reusable-definition] Saving the bundle records the allocation rules. It does not create or reserve any device. ## Preview an allocation [#preview-an-allocation] Preview the bundle before assigning it. Layer evaluates the kit against inventory that is available at that moment and returns: * The existing devices selected for the recipient. * Required shortages that block a complete allocation. * Optional shortages that do not erase otherwise valid matches. * Any administrator overrides applied to the proposed selection. Availability is evaluated at preview and assignment time. A device selected in an earlier preview can become unavailable if another workflow assigns it first. ## Assign the bundle [#assign-the-bundle] ### Choose the recipient [#choose-the-recipient] Select the person who should receive the kit. ### Review the proposed devices [#review-the-proposed-devices] Confirm the serialized assets Layer selected. If the interface offers an override, use it to choose a different available device. ### Resolve required shortages [#resolve-required-shortages] Add inventory or adjust the proposed allocation when a required item is unavailable. Layer keeps shortages explicit rather than inventing a placeholder asset. ### Assign [#assign] Submit the allocation. Layer links the selected existing assets to the recipient and returns the assigned devices, the resulting status, and any remaining shortages. An allocation with unresolved required inventory can remain a **draft**. A completed allocation reports the existing assets that were assigned. In both cases, the response keeps shortages visible so an incomplete kit cannot look complete. ## What changes in inventory [#what-changes-in-inventory] Bundle assignment changes the ownership state of matched hardware; it does not manufacture new records. | Before assignment | After assignment | | ---------------------------------------------- | ------------------------------------------------------------------- | | A serialized device is available in inventory. | The same device is linked to the selected person. | | The bundle contains reusable allocation rules. | The bundle remains reusable for the next recipient. | | A required item has no available match. | The shortage remains explicit and the allocation can stay in draft. | To correct a device record, update [Asset inventory](/layer/asset-inventory). To recover equipment from someone who is leaving, use the [offboarding workflow](/layer/offboarding). ## Troubleshooting [#troubleshooting] ### A required item is short [#a-required-item-is-short] Confirm that a matching device exists and is available. If no suitable record exists, add or correct the real device in inventory before retrying the allocation. ### The preview changed before assignment [#the-preview-changed-before-assignment] Another workflow may have allocated one of the proposed devices. Run the preview again and review the new matches. ### I need a SaaS seat or cloud resource [#i-need-a-saas-seat-or-cloud-resource] Asset bundles currently allocate existing serialized hardware. Manage applications, licenses, and cloud resources through their dedicated Layer workflows rather than representing them as bundle-created assets. # Asset inventory (/layer/asset-inventory) Layer's asset inventory is a single workspace for everything you own — laptops, monitors, SaaS subscriptions, software licenses, cloud resources, and vendor relationships. Most assets are discovered automatically through your [integrations](/layer/integrations/overview), but you can also add anything Layer can't see — a personal laptop on loan, a niche tool no connector covers, or a hardware purchase that hasn't reconciled yet — by hand or by CSV upload. ## Asset types [#asset-types] | Type | Description | | ------------------ | ------------------------------------------------------------------------ | | **Device** | Laptops, monitors, phones, peripherals, and any other physical hardware. | | **SaaS app** | A SaaS subscription or web application. | | **License** | A software license tied to a specific vendor and seat count. | | **Cloud resource** | A specific resource in AWS, Azure, GCP, or another cloud provider. | | **Vendor** | A vendor or supplier relationship. | Each asset has a **status** — `active`, `inactive`, `managed`, or `under_review` — plus a free-form `metadata` blob for type-specific fields like serial number, monthly cost, seat count, or renewal date. ## Add an asset manually [#add-an-asset-manually] ### Open the assets page [#open-the-assets-page] Go to **Assets** in your Layer dashboard and click **New Asset**. ### Pick an asset type [#pick-an-asset-type] The form adapts to the type you choose. For a **Device** you'll see fields for serial number, model, manufacturer, purchase date, and monthly cost. For a **SaaS app**, you'll see vendor, URL, monthly cost, and total seats. For a **License**, you'll see license type, seats, annual cost, and renewal date. ### Fill in the details [#fill-in-the-details] Only **Name** is required. All other fields go into the asset's metadata and become available across the rest of Layer — for example, a `cost_monthly` field shows up in [spend management](/layer/spend-management), and a `renewal_date` feeds the renewal calendar. ### Create the asset [#create-the-asset] Click **Create Asset**. The asset appears in the inventory immediately with `discovery_source: manual`. Only **Admin** and **Owner** roles can create or modify assets. ## Bulk-import from CSV [#bulk-import-from-csv] For larger imports — migrating from a spreadsheet, onboarding a new business unit, or a one-time hardware audit — upload a CSV instead of creating assets one at a time. ### CSV format [#csv-format] | Column | Required | Notes | | ------------------ | -------- | ---------------------------------------------------------------------------------------------------- | | `name` | Yes | The asset name. | | `asset_type` | No | Defaults to `device`. Must be one of `device`, `saas_app`, `license`, `cloud_resource`, or `vendor`. | | `status` | No | Defaults to `active`. Must be one of `active`, `inactive`, `managed`, or `under_review`. | | `canonical_id` | No | A stable ID for upserts. Auto-generated if omitted. | | *any other column* | No | Any other column becomes a metadata field on the asset. | Common metadata columns include `serial_number`, `model`, `manufacturer`, `cost_monthly`, `vendor`, `seats_total`, `renewal_date`, and `purchase_date`. You can include any column name you want — Layer stores extras as-is on the asset's metadata. ### Example CSV [#example-csv] ```csv asset_type,name,status,serial_number,model,manufacturer,cost_monthly device,MacBook Pro 16-inch,active,C02XJ0JAJGH7,MacBook Pro 16,Apple,150 device,Dell U2722D Monitor,active,,U2722D,Dell,20 saas_app,Slack,active,,,,15 license,Adobe Creative Cloud,active,,,,60 ``` Quoted fields with embedded commas, quotes, or newlines are supported. ### Import [#import] ### Open the import dialog [#open-the-import-dialog] Go to **Assets** and click **Import CSV**. ### Upload the file [#upload-the-file] Drag a CSV file onto the drop zone or click to browse. Layer shows a preview of the first five rows so you can confirm the columns parsed correctly. If you don't have a starting CSV, click **Download template CSV** for a ready-to-edit example. ### Run the import [#run-the-import] Click **Import**. Layer creates assets row by row and returns a summary with how many were created and a per-row error list for any that failed validation. CSV imports are capped at **1,000 rows** per upload. Split larger files into multiple imports. ### Error handling [#error-handling] Each row is validated independently. If row 12 has an invalid `asset_type`, Layer reports it but still creates the rest of the rows that pass validation. The response surfaces the original row number (counting the header as row 1) so you can fix the source spreadsheet and re-upload only what failed. ## Manual versus discovered assets [#manual-versus-discovered-assets] Manually-created assets and integration-discovered assets live side by side in the same inventory. They're distinguished by their `discovery_source` — `manual` for hand-created or CSV-imported assets, and source-specific values like `google_workspace`, `github`, or `aws` for discovered ones. If a manual asset later turns up through a connector with a matching `canonical_id`, Layer reconciles them into a single record. Set `canonical_id` on your manual rows when you know what the connector will use (for example, an email address for a SaaS user) so the records merge cleanly on the next sync. ## Provision a bundle of assets to a user [#provision-a-bundle-of-assets-to-a-user] To allocate a repeatable hardware kit — for example, a laptop and monitor for a new hire — use [asset bundles](/layer/asset-bundles). Bundles match the kit against existing serialized devices, surface required and optional shortages, and never create synthetic assets. Manage SaaS applications and licenses through their dedicated Layer workflows. # Audit log (/layer/audit-log) The audit log records every significant action in your Layer workspace — integration connections, asset changes, user role updates, data exports, and more. Every entry is scoped to your organization and immutable once written, so you have a tamper-proof trail for security investigations, compliance audits, and internal reviews. ## What gets logged [#what-gets-logged] Layer automatically records events across these categories: | Category | Example events | | ---------------- | ------------------------------------------------------------------------------------ | | **Integrations** | Connected, disconnected, sync started, sync completed, sync failed, re-auth required | | **Assets** | Created, updated, deleted | | **Users** | Invited, role changed, removed | | **Contracts** | Uploaded | | **Exports** | CSV generated | | **API keys** | Created, revoked | | **Workspace** | Settings changed | Each event captures: * **Who** — the user (or system process) that performed the action, including their email and IP address. * **What** — the event type, category, action, and whether it succeeded or failed. * **What it affected** — the resource type, identifier, and a human-readable path. * **When** — a UTC timestamp. * **Context** — free-form metadata such as old and new values, affected scopes, or error details. ## View the audit log [#view-the-audit-log] Go to **Settings → Audit log** in your Layer dashboard. The log displays the most recent events first and includes columns for time, action, resource, actor, and details. You can filter events by: * **Action** — narrow to a specific event type (e.g. `integration.connected`). * **Search** — free-text search across action names, resource types, and resource identifiers. ## Event types [#event-types] The following event types are currently tracked. New event types are added as Layer features expand. | Event type | Description | | ----------------------------- | ------------------------------------- | | `integration.connected` | A new integration was connected | | `integration.disconnected` | An integration was removed | | `integration.sync_started` | A sync cycle began | | `integration.sync_completed` | A sync cycle finished successfully | | `integration.sync_failed` | A sync cycle failed | | `integration.reauth_required` | An integration needs re-authorization | | Event type | Description | | --------------- | --------------------------------------- | | `asset.created` | A new asset was added to the inventory | | `asset.updated` | An asset record was modified | | `asset.deleted` | An asset was removed from the inventory | | Event type | Description | | ------------------- | --------------------------------------- | | `user.invited` | A new user was invited to the workspace | | `user.role_changed` | A user's role was changed | | `user.removed` | A user was removed from the workspace | | Event type | Description | | ----------------- | -------------------------------------- | | `api_key.created` | A browser extension API key was minted | | `api_key.revoked` | An API key was revoked | | Event type | Description | | ---------------------------- | -------------------------------- | | `contract.uploaded` | A contract document was uploaded | | `export.csv_generated` | A CSV export was generated | | `workspace.settings_changed` | Workspace settings were modified | ## Data retention [#data-retention] Audit log entries are retained for six years in accordance with HIPAA requirements. Entries cannot be edited or deleted by any user — only automated retention processes remove records after the retention period expires. ## Permissions [#permissions] All members of your organization can view the audit log. Only the application layer (running with elevated privileges) can write new events. No user can insert, update, or delete audit log entries directly. The audit log is designed for compliance and investigations. If you need to export audit data for a specific review, use the CSV export on the **Settings → Audit log** page or contact [support@axiomancer.io](mailto:support@axiomancer.io) for bulk export assistance. # Plans and billing (/layer/billing) Axiom Layer offers four plans — Free, Starter, Growth, and Scale. Every new workspace starts on the Free plan. You can upgrade, downgrade, or cancel at any time from **Settings → Billing**. ## Plans [#plans] | | Free | Starter | Growth | Scale | | -------------------------- | --------------------- | -------------- | -------------- | -------------- | | **Price (monthly)** | $0 | $299/mo | $599/mo | $999/mo | | **Price (annual)** | $0 | $249/mo | $499/mo | $833/mo | | **Employee limit** | 25 | 50 | 200 | 500 | | **Integrations** | Google Workspace only | All connectors | All connectors | All connectors | | **Dashboard** | Basic | Full discovery | Full discovery | Full discovery | | **Email alerts** | — | ✓ | ✓ | ✓ | | **CSV export** | — | ✓ | ✓ | ✓ | | **Renewal calendar** | — | ✓ | ✓ | ✓ | | **Spend budgets** | — | — | ✓ | ✓ | | **Custom categories** | — | — | ✓ | ✓ | | **Contract AI extraction** | — | — | ✓ | ✓ | | **API access** | — | — | — | ✓ | | **AI usage tracking** | — | — | — | ✓ | | **Priority support** | — | — | — | ✓ | Annual billing saves you two months per year compared to monthly billing. ## Subscribe to a paid plan [#subscribe-to-a-paid-plan] ### Open the billing page [#open-the-billing-page] Go to **Settings → Billing** in your Layer dashboard. ### Choose monthly or annual billing [#choose-monthly-or-annual-billing] Use the toggle at the top of the plan picker. Annual billing is discounted. ### Select a plan [#select-a-plan] Click **Subscribe** on the plan you want. You'll be redirected to a secure Stripe Checkout page. ### Complete payment [#complete-payment] Enter your payment details and confirm. Promotion codes are accepted at checkout. Once payment succeeds, your workspace is upgraded immediately. ## Promotion codes [#promotion-codes] Stripe Checkout for Layer accepts promotion codes — when you reach the **Subscribe** step, click **Add promotion code** above the payment form and paste the code before completing payment. Codes apply to both monthly and annual billing unless otherwise noted. | Code | Discount | Notes | | ---------- | -------------------------- | ------------------------------------------------------------------------------------------------------- | | `LAYER50` | 50% off the first 3 months | Layer launch promo | | `ANNUAL10` | 10% off once | Stacks with the annual price; one-time use per workspace | | `FOUNDER` | 100% off forever | Limited redemptions; reach out to [support@axiomancer.io](mailto:support@axiomancer.io) for eligibility | The same promotion code field is enabled in checkout for **Locus** (`LOCUS50`), **Overwatch** (`OVERWATCH50`), and **Codex** (`CODEX50`), and `ANNUAL10` and `FOUNDER` are honored across all four products. If you don't see the **Add promotion code** link at checkout, refresh the page — Stripe occasionally cold-loads the field after the cart line item resolves. ## Manage your subscription [#manage-your-subscription] After you subscribe, a **Manage billing** button appears on the billing page. Click it to open the Stripe Customer Portal, where you can: * Update your payment method * Switch between plans * Change from monthly to annual billing (or vice-versa) * View and download past invoices * Cancel your subscription When you cancel, your workspace reverts to the Free plan at the end of the current billing period. No data is deleted. ## Permissions [#permissions] Only **Owner** and **Admin** roles can subscribe to a paid plan or open the Stripe Customer Portal. Members and auditors see the billing page but the **Subscribe** and **Manage billing** actions return `403 Insufficient permissions` if invoked. The role check runs before any Stripe customer or session is created, so non-admin clicks never touch Stripe state. Promote a teammate to Admin from **Settings → Team** to delegate billing. ## Feature gating [#feature-gating] Certain features are only available on specific plans. If you try to use a feature that requires a higher plan, Layer shows an upgrade prompt with a direct link to the billing page. The table above lists which features unlock at each tier. ## Frequently asked questions [#frequently-asked-questions] Layer still syncs data, but the dashboard flags that you've exceeded your plan's limit. Upgrade to a higher plan to remove the restriction. Yes. Stripe prorates the charge automatically. You only pay the difference for the remaining days in your billing cycle. Layer accepts all major credit and debit cards through Stripe. Contact [support@axiomancer.io](mailto:support@axiomancer.io) within 14 days of a charge for a full refund. Stripe retries the charge automatically. After three failed attempts, your subscription is marked as past due and you'll receive a notification to update your payment method. # Browser extension (/layer/browser-extension) The AxiomLayer Discovery browser extension detects which web applications your team uses — including tools that weren't provisioned through official channels. It runs silently in the background and reports usage data back to your Layer workspace so you can identify shadow IT, measure adoption, and spot redundant subscriptions. Discovered apps that don't match your SaaS catalog are auto-classified and routed to the [Rogue Stack review queue](/layer/rogue-stack). ## What the extension tracks [#what-the-extension-tracks] * **Domain visits** — which SaaS applications are accessed and how much time is spent on each. * **Login events** — when someone signs in to a web application (detected by the presence of password and email fields in forms). * **Active vs. passive time** — focused time (tab is active) vs. background time, so you can distinguish apps people actively use from tabs left open. The extension does **not** read page content, emails, messages, or any data within applications. It only observes domain-level navigation and login form submissions. ## Install the extension [#install-the-extension] ### Get the extension [#get-the-extension] Install **AxiomLayer Discovery** from the Chrome Web Store, or deploy it through your organization's managed Chrome policy. ### Connect to your workspace [#connect-to-your-workspace] Open the extension popup and enter your Layer workspace URL and API key. You can find your API key in **Settings** in your Layer dashboard. ### Start discovering [#start-discovering] The extension begins tracking immediately. Usage data syncs to your Layer workspace every minute. ## Managed deployment [#managed-deployment] For organization-wide rollout, you can deploy the extension via Google Workspace admin or your MDM solution. The extension supports managed configuration through Chrome's `managed_schema`, allowing you to pre-set the workspace URL and API key so end users don't need to configure anything. ## How syncing works [#how-syncing-works] The extension batches usage data locally and syncs it to Layer every minute. If the sync fails (due to network issues or server errors), the extension retries with exponential backoff — starting at 5 seconds and increasing up to 5 minutes, for a maximum of 6 attempts. Each sync payload includes an idempotency key to prevent duplicate data. ## What happens to discovered data [#what-happens-to-discovered-data] Once usage data reaches your Layer workspace, it flows into the same asset-discovery pipeline as your other sources: * **Catalog matching** — each observed domain is matched against your SaaS catalog by domain, subdomain, and known aliases. Matched apps increment usage and adoption metrics on the existing asset record. * **Shadow IT routing** — domains that don't match any catalog entry are queued in the [Rogue Stack review queue](/layer/rogue-stack), where Layer's two-stage classifier (catalog lookup, then LLM classification) identifies the underlying product. * **Spend correlation** — when a discovered app matches a contract or expense record, Layer correlates usage with spend so you can spot licenses that are paid for but unused — the raw material for [license harvesting](/layer/spend-management#license-harvesting). ## Troubleshooting [#troubleshooting] Check that the workspace URL and API key are correct in the extension popup (they must match **Settings** in your Layer dashboard). Then confirm the extension has permission to run on all sites — managed Chrome policies can restrict it to specific domains. Data syncs once per minute, so allow up to 60 seconds after first connecting. The extension only observes domain-level navigation in tabs where it has permission. Apps embedded inside other domains (e.g. a tool loaded in an iframe on a portal) may not be attributed correctly. Login detection also requires the app to use standard password/email form fields — passwordless or SSO-only apps are tracked by domain visit rather than login event. Yes — the extension icon shows an active indicator while tracking, and clicking it displays the current workspace connection. Layer is designed for transparent shadow-IT discovery, not covert surveillance: the extension never reads page content, emails, or in-app data, only domain-level navigation and login form presence. Use Chrome's built-in per-site extension controls to disable AxiomLayer Discovery on sensitive domains (e.g. banking or HR portals). The extension will stop observing those domains entirely. ## Privacy [#privacy] The extension requests only the permissions it needs: | Permission | Purpose | | ---------- | --------------------------------------------- | | `tabs` | Detect which domain is active | | `storage` | Store configuration and buffered data locally | | `alarms` | Schedule periodic syncs | The extension runs a content script on web pages solely to detect login form submissions. It does not inject UI, modify pages, or read page content beyond form field detection. # Contract management (/layer/contracts) Layer's contract management lets you upload vendor agreements, extract key terms automatically with AI, and stay ahead of renewals with urgency-based alerts. Every contract is linked to your asset inventory so you can see costs, utilization, and renewal deadlines in one place. ## Upload a contract [#upload-a-contract] You can add contracts in two ways: * **Upload a file** — drag and drop a PDF or TXT file (up to 5 MB) into the upload form. * **Paste text** — copy the contract text directly into the text field. Go to **Contracts** in your Layer dashboard and click **Upload**. ## AI-powered extraction [#ai-powered-extraction] Contract AI extraction is available on the **Growth** plan and above. When you upload a contract, Layer can extract structured metadata automatically. Click **Extract with AI** and Layer analyzes the document to identify: | Field | Description | | ------------------ | --------------------------------------------------------- | | **Vendor name** | The counterparty or service provider | | **Contract value** | Total monetary value | | **Seat count** | Number of licensed users or seats | | **Effective date** | When the contract takes effect | | **Expiry date** | When the contract ends | | **Renewal date** | When the contract renews | | **Auto-renewal** | Whether the contract renews automatically | | **Notice days** | Days of advance notice required to cancel or change terms | ### Confidence scores [#confidence-scores] Each extracted field includes a confidence score (0–100%) and a source excerpt — the exact passage from the contract that supports the extracted value. This lets you verify the AI's work before saving. ### Human-in-the-loop confirmation [#human-in-the-loop-confirmation] Before saving an AI-extracted contract, you must confirm the following fields manually: * Effective date * Expiry date * Renewal date * Contract value This prevents errors in critical financial and scheduling data. Fields that weren't extracted (null values) don't require confirmation. ## Renewal tracking [#renewal-tracking] Layer monitors every contract with a renewal date and alerts you based on urgency: | Urgency | Days until renewal | | ------------ | ------------------ | | **Critical** | 7 days or fewer | | **Warning** | 8–30 days | | **Upcoming** | 31–60 days | | **Soon** | 61–90 days | | **Ok** | More than 90 days | ### Auto-renewal notice deadlines [#auto-renewal-notice-deadlines] For contracts with auto-renewal enabled and a notice period, Layer calculates the **action-required-by date** — the last day you can cancel or renegotiate before the contract auto-renews. Alerts are based on this deadline rather than the renewal date itself, so you're warned in time to act. ### Snooze alerts [#snooze-alerts] If you've already handled a renewal or want to suppress alerts temporarily, you can snooze alerts on a per-contract basis. Snoozed contracts are excluded from renewal alerts until the snooze period expires. ## Renewal recommendations [#renewal-recommendations] Layer analyzes your contracts alongside spend data to generate renewal recommendations: | Action | When Layer suggests it | | --------------- | ----------------------------------------------------------- | | **Negotiate** | Spend or utilization data suggests you can get better terms | | **Renew** | The contract is performing well and should be renewed as-is | | **Downgrade** | Usage is below the contracted tier | | **Cancel** | The tool shows low or no usage | | **Consolidate** | Multiple contracts cover overlapping functionality | Recommendations include estimated annual savings so you can prioritize high-impact actions. ## Manual contract entry [#manual-contract-entry] If you prefer not to use AI extraction, click **Manual contract** on the contracts page to enter all fields by hand. # Demo mode (/layer/demo-mode) Demo mode is a flag on a Layer organization that turns it into a fully-populated synthetic workspace. It exists so prospects, internal reviewers, and trial users can explore every Layer surface — apps, contracts, spend, AI usage, integrations — with realistic data, without connecting any real systems and without any risk to production tenants. A demo organization renders identically to a real one, with two additions: * A pink **Demo data** banner under the cross-product bar on every page, marking the workspace as synthetic. * A **Demo mode** card in **Settings** with a one-click **Reset demo data** action. Demo mode is opt-in per organization and **off by default**. Real customer tenants are never eligible for the reset endpoint or the seeded data — the server hard-refuses any reset request unless the organization is explicitly flagged as demo. ## When to use demo mode [#when-to-use-demo-mode] Use a demo organization when you want to: * Walk a prospect through Layer end-to-end without staging real integration credentials. * Click through every page (Apps, Contracts, Spend, AI Usage, Renewals, People, Integrations) with realistic data — 60+ SaaS apps, 12 months of spend, 18+ contracts spread across the next 12 months, and 12 months of AI usage across OpenAI, Anthropic, and GitHub Copilot. * Reset to a known-good seeded state at the start of every demo or training session. * Reproduce dashboard behavior — needs-reauth integrations, active connections, spend trends — that would otherwise require multi-day real-world data accumulation. For real production usage, leave `is_demo` unset. The reset action is unavailable on non-demo organizations and the banner does not render. ## What gets seeded [#what-gets-seeded] Resetting a demo organization wipes nine tenant-scoped tables in foreign-key order, then re-seeds them. The seed currently produces: | Surface | Volume | | ----------------------- | ------------------------------------------------------------------------------------------------------- | | SaaS apps | 60+ across productivity, dev, security, compliance, finance, HR, marketing, sales, and AI categories | | Spend records | 12 months of monthly spend per app | | Contracts | 18+ contracts spread across the next 12 months of renewals | | AI usage | 12 months of records across OpenAI, Anthropic, and GitHub Copilot | | Integration connections | A mix of active connections and `needs_reauth` rows so the **Integrations** page shows realistic states | The exact counts returned by the most recent reset are surfaced inline on the **Demo mode** card after the action completes. ## Reset demo data [#reset-demo-data] ### Open the Demo mode card [#open-the-demo-mode-card] In a demo organization, go to **Settings**. The **Demo mode** card renders only when `is_demo=true` on your organization. If you don't see it, the workspace isn't a demo tenant and the reset action is not available to you. ### Click Reset demo data [#click-reset-demo-data] The card asks you to confirm before performing any destructive work. ### Confirm the wipe and re-seed [#confirm-the-wipe-and-re-seed] Click **Yes, wipe and re-seed**. Layer wipes every seeded table for your organization, then re-runs the seed. When it finishes, a green status row reports how many apps, devices, people, contracts, spend records, and AI usage records were re-created. The action takes a few seconds. Refreshing the dashboard after a reset shows the freshly-seeded inventory immediately. Reset is destructive. It deletes every row in the seeded tables for the organization before re-seeding. Anything you created or edited inside a demo workspace — manual contracts, custom fields, comments — is wiped along with the seeded data. ## Permissions [#permissions] Only **Admin** and **Owner** roles can trigger a reset. Members see the **Demo mode** card if it renders for the organization, but the action returns `403 Insufficient permissions` if invoked by a non-admin. ## Safety guarantees [#safety-guarantees] * The reset endpoint (`POST /api/seed/reset`) refuses with `403 Reset is only available for demo organizations.` whenever the target organization's `is_demo` flag is unset. Real tenants cannot be wiped through this surface, even by an admin. * The endpoint runs through the service-role Supabase client only after the demo check passes. Authorization happens before any destructive work. * The pink banner is rendered unconditionally on every dashboard page when `is_demo=true`, so a demo workspace cannot be mistaken for a real one at a glance. ## Turning a workspace into a demo [#turning-a-workspace-into-a-demo] Demo mode is controlled by the `is_demo` boolean column on `organizations`. It defaults to `false`. To convert a workspace to demo mode, an Axiom operator flips the flag in the database for that tenant — there is no in-app toggle by design, since flipping the flag enables a destructive action. Reach out to [support@axiomancer.io](mailto:support@axiomancer.io) if you need a demo organization provisioned. A public per-visitor demo CTA and ephemeral auto-purging demo organizations are on the roadmap. Until then, demo organizations are provisioned manually and persist until an operator removes them. # Get started with Layer (/layer/getting-started)

Layer spend management dashboard showing total SaaS spend, applications tracked, AI spend, top applications by spend, and a spend-by-department breakdown

### Create your workspace [#create-your-workspace] Sign up at [app.axiomlayer.io](https://app.axiomlayer.io). You'll need an admin email on your company domain. Sign-up routes through Auth0 Universal Login — pick Google Workspace, Microsoft, or any identity provider configured for your tenant, complete sign-in there, and you're returned to Layer. On your first sign-in, Layer presents a one-field **Create your workspace** page where you provide the workspace name and are added as the owner. Layer never infers a workspace name from your email domain. ### Invite your team [#invite-your-team] Open **Settings → Team** and add the people who'll need access. Roles: Owner, Admin, Member. ### Connect your first integration [#connect-your-first-integration] Head to **Integrations** and click Connect on Google Workspace, Microsoft 365, or your IdP. See the [integrations overview](/layer/integrations/overview) for the full catalog. ### Wait for the first sync [#wait-for-the-first-sync] Most connectors finish their initial pull within 10–30 minutes. The dashboard will populate as data arrives. The workspace name is captured on the **Create your workspace** page that runs on first sign-in after Auth0. You can rename the workspace any time from **Settings**. If sign-up redirects you back to the login page with an "We couldn't finish setting up your organization" banner, the message in parentheses is the underlying reason from the provisioner. On hosted Layer this should never happen — retry once, then email support if it persists. On self-hosted or preview deployments, the most common cause is a missing or misconfigured Supabase service-role key on the app environment. Need help? Email [support@axiomancer.io](mailto:support@axiomancer.io) or open the in-app chat. # Axiom Layer (/layer) Sign up, invite your team, and connect your first integration. Browse the full catalog of connectors and their setup guides. ## What Layer covers [#what-layer-covers] * **People** — employees synced from your HRIS or IdP, with cost-per-headcount roll-ups. * **Apps** — every SaaS subscription discovered through email, finance, IdP, and browser extension. * **Hardware** — laptops, monitors, and accessories with amortized cost and lifecycle status. * **AI usage** — token spend across OpenAI, Anthropic, and other providers, broken down by employee. Layer ships weekly — follow release notes for Layer and the rest of the platform in the [changelog](/changelog). # Integration health alerts (/layer/integration-health-alerts) Layer monitors the health of every connected integration and sends a daily email summary to workspace admins when something needs attention. The digest covers two states: * **Sync failing** — the connector encountered errors during its last sync attempt. * **Needs re-authorization** — the OAuth token expired or an admin revoked consent, and the connector can no longer pull data. If all integrations are healthy, no email is sent. ## How it works [#how-it-works] Layer runs a scheduled health check every day at 09:00 UTC. The check scans every integration connection across your workspace, groups any degraded connections by organization, and emails the admin contacts for each affected org. Each email includes: * A count of connections that need attention. * A breakdown by failure type — failing syncs and re-authorization requests are listed separately. * A direct link to the [integrations page](/layer/integrations/overview) so you can resolve issues in one click. ## Who receives the email [#who-receives-the-email] The digest is sent to every user in your workspace who has an **Admin** or **Owner** role. Layer pulls admin contacts from your synced identity provider, so you don't need to configure a recipient list manually. ## Opting out [#opting-out] You can unsubscribe from integration health emails in **Settings → Notifications**. Unsubscribing only affects your account — other admins in the workspace continue to receive the digest. ## Resolving flagged integrations [#resolving-flagged-integrations] When the email reports a failing sync or a re-authorization issue: ### Open the integrations page [#open-the-integrations-page] Click the **Resolve in dashboard** button in the email, or go to **Integrations** in Layer. ### Find the flagged connector [#find-the-flagged-connector] Look for connectors with a red or amber status badge. The badge matches the issue type described in the email. ### Fix the issue [#fix-the-issue] * **Needs re-authorization** — click **Reconnect** on the connector card to re-run the OAuth flow. * **Sync failing** — check the error message on the connector detail view. Common causes include revoked API keys, permission changes, or service outages on the provider side. ### Verify the next sync [#verify-the-next-sync] After reconnecting or fixing credentials, Layer triggers an immediate sync. The connector status updates once the sync completes. ## Troubleshooting [#troubleshooting] Layer identifies admins through your synced identity provider. Make sure your user record in the IdP has an admin or owner role, and that the IdP integration is actively syncing. Also check your spam folder — the email comes from `noreply@axiomlayer.io`. The health check runs at 09:00 UTC. If you fixed the issue after the check ran, the next day's email will reflect the updated status. You can verify current status on the [integrations page](/layer/integrations/overview) at any time. Individual admins can unsubscribe in **Settings → Notifications**. There is no workspace-wide toggle — each admin controls their own subscription independently. # MCP server (/layer/mcp-server) Layer exposes an MCP-compatible server that lets AI agents and LLM-powered tools query your workspace data programmatically. If you use tools like Claude Desktop, Cursor, or custom AI agents, the MCP server gives them read access to your assets, discovered apps, and compliance controls. The MCP server requires API access, available on the **Scale** plan. ## Endpoint [#endpoint] ```http POST https://app.axiomlayer.io/api/mcp ``` The server implements the [Model Context Protocol](https://modelcontextprotocol.io/) (JSON-RPC 2.0). It supports three standard MCP methods: * `initialize` — returns server capabilities. * `tools/list` — lists available tools. * `tools/call` — executes a tool and returns results. A `GET` request to the same URL returns server metadata (name, version, and available tools). ## Authentication [#authentication] All requests must include a valid session. The MCP server uses the same authentication as the rest of the Layer API — requests are scoped to your organization automatically. ## Available tools [#available-tools] | Tool | Description | | ------------------------ | -------------------------------------------------------------------------------- | | `axiomlayer_list_assets` | List assets (SaaS apps, devices, users) in your workspace | | `drift_list_apps` | List discovered shadow IT apps from drift detection | | `codex_list_controls` | List compliance controls with framework metadata | | `platform_get_overview` | Get a cross-product summary with counts of assets, discovered apps, and controls | ### Common parameters [#common-parameters] Every tool accepts these optional parameters: | Parameter | Type | Description | | --------- | --------------- | --------------------------------------------------------- | | `limit` | integer (1–200) | Maximum number of results to return | | `status` | string | Filter results by status | | `search` | string | Case-insensitive text search across names and identifiers | ### Example request [#example-request] ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "axiomlayer_list_assets", "arguments": { "limit": 10, "search": "slack" } } } ``` ### Example response [#example-response] ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "Found 2 assets matching 'slack'..." } ], "structuredContent": { "assets": [ { "id": "asset_abc123", "name": "Slack", "asset_type": "application", "status": "active" } ], "count": 2 } } } ``` ## Use with Claude Desktop [#use-with-claude-desktop] To connect Layer to Claude Desktop, add the MCP server to your Claude Desktop configuration: ```json { "mcpServers": { "axiomlayer": { "url": "https://app.axiomlayer.io/api/mcp" } } } ``` Once connected, you can ask Claude questions like "What SaaS apps does my company use?" or "Show me all shadow IT apps" and it will query your Layer workspace directly. # Notifications (/layer/notifications) Layer's notification system lets you route alerts to the right people through the channels they already use. You can configure notification channels and rules in **Settings → Notifications**. ## Channels [#channels] Layer supports three notification channels: | Channel | Configuration | | ----------- | ---------------------------------------------------- | | **Email** | A list of recipient email addresses | | **Slack** | A Slack incoming webhook URL | | **Webhook** | A URL and a shared secret for signature verification | You can create multiple channels of each type — for example, separate Slack channels for IT alerts and finance alerts. ### Webhook security [#webhook-security] Webhook notifications include an `x-webhook-signature` header containing an HMAC-SHA256 signature of the request body, computed using your shared secret. Verify this signature on your end to confirm the notification came from Layer. ## Notification rules [#notification-rules] Rules connect events to channels. Each rule specifies: * **Event type** — what triggers the notification. * **Channel** — where the notification is delivered. * **Enabled/disabled** — toggle rules on or off without deleting them. You can create multiple rules for the same event to send notifications to different channels simultaneously. ## Event types [#event-types] | Event type | Description | | --------------------------- | ------------------------------------------------------------------ | | **Renewal approaching** | A contract renewal date is within your configured lookahead window | | **Shadow app detected** | A new unmanaged application was discovered | | **Control failing** | A compliance control dropped below the passing threshold | | **Control passing** | A previously failing compliance control is now passing | | **Evidence expiring** | Compliance evidence is approaching its expiration date | | **Access review due** | An access review campaign deadline is approaching | | **Questionnaire completed** | A vendor security questionnaire was completed | | **Monitor alert** | An integration health monitor detected an issue | | **License harvest ping** | An unused license candidate was identified for reclamation | Start with the events that matter most to your team. You can always add more rules later without affecting existing notifications. ## Set up notifications [#set-up-notifications] ### Create a channel [#create-a-channel] Go to **Settings → Notifications** and click **Add channel**. Choose the channel type (email, Slack, or webhook) and provide the required configuration. ### Add notification rules [#add-notification-rules] For each event you want to be notified about, click **Add rule**, select the event type and the channel, then save. ### Test the channel [#test-the-channel] Use the **Send test** button to verify your channel is configured correctly before relying on it for production alerts. Email notifications require the **Starter** plan or above. Slack and webhook channels require the **Growth** plan or above. # Offboarding (/layer/offboarding) When someone leaves your organization, Layer automates the offboarding process — revoking app access, reclaiming licenses, and tracking hardware returns. Offboarding tasks are created automatically when Layer detects a termination event from your HRIS or identity provider. ## How offboarding works [#how-offboarding-works] ### Termination detected [#termination-detected] Layer receives a termination event from your connected HRIS (e.g. BambooHR, Gusto, Rippling) or identity provider. The event includes the departing employee's identity, last working day, manager, and return shipping address (if available). ### Task created [#task-created] Layer creates an offboarding task for the employee. It queries the employee's assigned assets and generates a per-app action plan automatically. ### Actions executed [#actions-executed] Layer executes each action through your connected integrations, with automatic retries for transient failures. ### Hardware return tracked [#hardware-return-tracked] If the employee has assigned devices, Layer initiates the hardware return workflow with shipping labels, tracking, and escalation. ## Action types [#action-types] Layer determines the correct action for each asset based on the asset type and authentication method: | Action | When it applies | | ----------------------- | ------------------------------------------------------------------ | | **Revoke OAuth** | Apps connected via OAuth tokens | | **Revoke SSO** | Apps accessed through single sign-on | | **Remove license** | Licensed seats that should be reclaimed | | **Transfer data** | Assets that require data handoff before removal | | **Queue device return** | Physical devices (laptops, monitors, phones) | | **Flag for review** | Assets that don't match other categories and need manual attention | Each action moves through these statuses: **Pending** → **In progress** → **Completed** (or **Partial** if only partially successful). ## Deduplication [#deduplication] Layer prevents duplicate offboarding tasks for the same employee. If a task already exists in a `pending` or `in_progress` state, new termination events for that employee are ignored. This is enforced both at the application level and by a database constraint. ## Hardware returns [#hardware-returns] When a departing employee has assigned devices, Layer tracks the full return lifecycle: ### Return statuses [#return-statuses] | Status | Meaning | | ---------------------- | --------------------------------------------------- | | **Queued** | Return initiated, awaiting shipping label | | **Label generated** | Shipping label created and sent to employee | | **In transit** | Carrier confirms the package is on its way | | **Received** | Package delivered to your return facility | | **Inspection pending** | Device arrived and awaiting physical inspection | | **Completed** | Inspection passed, device processed | | **SLA breached** | Return did not arrive within the expected timeframe | ### Escalation schedule [#escalation-schedule] If an employee hasn't returned their device, Layer escalates automatically: | Day | Action | | ---------- | ------------------------------------ | | **Day 7** | Reminder sent to the employee | | **Day 14** | Alert sent to the IT lead | | **Day 21** | Alert sent to the employee's manager | | **Day 30** | Alert sent to the finance team | Escalation notifications are sent via your configured [notification channels](/layer/notifications). ### Device inspection [#device-inspection] When a device is received, it goes through an inspection checklist: * Screen cracks * Dents or physical damage * Missing keys * Port damage * Battery health issues * Accessories present ### Device disposition [#device-disposition] After inspection, devices are assigned a disposition: | Disposition | Meaning | | ----------------------- | ----------------------------------- | | **Awaiting wipe** | Queued for data wipe | | **Wiped and restocked** | Wiped and returned to inventory | | **Refurbishment queue** | Needs repair before reuse | | **Retired** | End of life, scheduled for disposal | # Rogue Stack review queue (/layer/rogue-stack) The **Rogue Stack** view surfaces every SaaS app Layer discovers across your tenant — from OAuth consents, SSO sign-ins, and expense receipts — and reconciles them against the catalog of known applications. Anything Layer can't confidently identify is routed to a **review queue** so a human can confirm what it is before it flows into spend, access, and offboarding workflows. ## How discovery classifies apps [#how-discovery-classifies-apps] Every analysis run walks each unresolved row from three raw discovery sources and tries to identify the underlying app: | Source | What it captures | | ------------------ | --------------------------------------------------------------------------------------------------------------- | | **OAuth grants** | Third-party apps users have granted access to via Google Workspace, Microsoft 365, or other identity providers. | | **SSO events** | Sign-ins observed through your IdP for apps that aren't already provisioned in Layer. | | **Email receipts** | Vendors extracted from expense and invoice emails forwarded to Layer. | For each unique app name, Layer runs a two-stage pipeline: 1. **Catalog match** — a pure database lookup against your SaaS catalog using domain, subdomain, OAuth client ID, and previously classified aliases. When it matches, Layer stamps the resolved catalog entry onto every source row for that app so it stops being re-scanned on subsequent runs. 2. **LLM classification** — if the catalog lookup returns *unknown*, Layer sends the signals (app name, domain, OAuth scopes) to Claude Haiku to identify the product. * **High confidence** results are auto-applied to your catalog and treated as a normal discovered app. * **Low confidence** results are queued in Rogue Stack as `review_pending` for an admin to confirm or reject. Catalog matching runs on every analysis pass regardless of configuration. Only the LLM step requires an API key — see [LLM classification](#llm-classification) below. ## What the review queue shows [#what-the-review-queue-shows] Open **Rogue Stack → Review queue** in your Layer dashboard. Each pending item includes: * The raw app or vendor name Layer observed. * The discovery source (OAuth, SSO, or email receipt) and the domain, client ID, or scopes it was seen with. * Claude's best guess at the product, with a confidence score and reasoning. * Suggested catalog matches you can accept in one click. For each item you can: * **Approve** the suggested match — Layer links every source row for that app to the chosen catalog entry. * **Reject** the suggestion and pick a different catalog entry, or mark the app as **Ignored** if it isn't a real SaaS tool (e.g. a personal Google account or a one-off receipt). Once resolved, the app disappears from the queue and won't be re-classified on future runs. If the review queue is empty and reads **"All clear"**, either every discovered app has already been matched, or the LLM classification step is disabled (see below). ## LLM classification [#llm-classification] Layer uses [Anthropic's Claude Haiku](https://www.anthropic.com/claude/haiku) to identify apps that don't match your catalog. This step is optional — without it, catalog matching still runs and back-fills known apps, but truly unknown apps will remain unresolved instead of appearing in the review queue. ### Enable it [#enable-it] Set `ANTHROPIC_API_KEY` on the Layer worker environment: ```bash export ANTHROPIC_API_KEY=sk-ant-... ``` Restart the worker. The next analysis run will start populating the review queue. ### Cost and rate limits [#cost-and-rate-limits] Classification is designed to be cheap and bounded: * **One Haiku call per newly discovered unknown app**, then cached — the same app is never classified twice. * **At most 25 LLM classifications per analysis run** across all sources combined. Remaining candidates roll over to the next run. * **Up to 200 catalog-match attempts per source per run** (the non-LLM step). * **Per-app failures are swallowed** — a bad response never breaks the analysis job. If you want to disable classification without removing the key, unset `ANTHROPIC_API_KEY` on the worker. Catalog matching and back-fill continue to run. ## When apps stop being re-scanned [#when-apps-stop-being-re-scanned] Layer writes the resolved catalog ID back onto every source row as soon as it's identified — whether by catalog match, LLM auto-apply, or an admin's decision in the review queue. Writes are idempotent, so a hand-curated match is never overwritten by a later automated one. This means an app you approve today won't show up in the queue again the next time it appears in an OAuth grant or SSO event, and your daily analysis cost stays flat regardless of how much new activity your tenant generates. ## Related [#related] * [Browser extension](/layer/browser-extension) — the client-side source of domain-visit discovery. * [Notifications](/layer/notifications) — alert your team when new apps land in the review queue. * [MCP server](/layer/mcp-server) — query discovered apps and review-queue state from Claude. # Spend management (/layer/spend-management) Layer's spend management tools help you understand where your software budget goes and take action to reduce waste. The spend dashboard aggregates subscription costs across every connected integration, and features like budgets, license harvesting, and virtual cards give you direct control over spend. ## Spend dashboard [#spend-dashboard] Go to **Spend** in your Layer dashboard. The page shows: * **Monthly spend trend** — a chart of total SaaS spend over time. * **Spend by application** — every app ranked by total cost, with monthly averages and record counts. * **Spend by department** — costs attributed to departments using your identity provider data. Unattributed spend is grouped separately. Connect your identity provider (Google Workspace, Microsoft 365, or Okta) to attribute spend to departments automatically. ## Budgets [#budgets] Budgets let you set spending limits and get alerts before you overshoot. Budgets are available on the **Growth** plan and above. ### Create a budget [#create-a-budget] ### Open the budgets page [#open-the-budgets-page] Go to **Spend → Budgets** in your Layer dashboard. ### Add a new budget [#add-a-new-budget] Click **Add budget** and fill in: * **Label** — a name for the budget (e.g. "Engineering SaaS" or "Company-wide"). * **Amount** — the spending limit in your chosen currency. * **Period** — the time window the budget covers. * **Alert threshold** — the percentage of the budget at which Layer sends an alert. Defaults to 90%. ### Save [#save] Click **Save**. Layer starts tracking spend against the budget immediately. ### Budget alerts [#budget-alerts] When actual spend reaches the alert threshold, Layer flags the budget in the dashboard. If spend exceeds the budget amount, the budget is marked as **overrun**. You can configure [notifications](/layer/notifications) to receive alerts via email, Slack, or webhook. ## License harvesting [#license-harvesting] License harvesting identifies seats assigned to people who haven't used the tool recently. Layer checks each license against the user's last activity date and flags candidates that exceed an inactivity threshold (default: 30 days). Harvesting candidates appear in the **Spend** section of your dashboard. For each candidate, you see: * The application name and user email. * How many days the license has been inactive. * The user's employment status (active, on leave, or terminated). You can then reclaim the seat directly with the vendor or use the information to negotiate a smaller renewal. ## Virtual cards [#virtual-cards] Virtual cards let you issue single-vendor cards with hard spending limits. Each card is tied to a specific vendor and cardholder, so you control exactly how much can be charged. ### Issue a virtual card [#issue-a-virtual-card] ### Open the virtual cards page [#open-the-virtual-cards-page] Go to **Spend → Virtual cards** in your Layer dashboard. ### Fill in the card details [#fill-in-the-card-details] * **Cardholder** — the person responsible for the card. * **Vendor** — the vendor the card is issued for. * **Spending limit** — the maximum amount in dollars. * **Period** — how often the limit resets: Daily, Weekly, or Monthly. * **Currency** — defaults to USD. ### Issue the card [#issue-the-card] Click **Issue card**. The card is created immediately and can be used for the specified vendor. ### Manage existing cards [#manage-existing-cards] From the virtual cards page you can: * **Adjust the spending limit** or reset period on any active card. * **Pause or deactivate** a card to stop all charges immediately. * **View transaction history** for each card. Virtual card authorization is enforced in real time. Charges that would exceed the card's spending limit are automatically declined. # Business licenses (/locus/business-licenses) The **Business Licenses** dashboard is a metro-spanning search surface over Locus's normalized business-license catalog. Use it to find recently issued, modified, or closed licenses by metro, address, NAICS code, or pioneer-tier classification, and to pull the result set as CSV for downstream territory and site-selection workflows. The page lives at [`/business-licenses`](https://app.axiomlocus.io/business-licenses) inside the Locus app and is backed by [`GET /api/business-licenses/search`](#api). ## When to use it [#when-to-use-it] Reach for this dashboard when you need to: * Track new business formation in a metro or neighborhood as a leading demand signal. * Find specific operators (by address or NAICS) before a site visit, deal screen, or territory review. * Pull a metro-scoped batch of licenses into a spreadsheet or CRM via CSV export. * Distinguish freshly-licensed activity ("Pioneer" tier) from longer-running operators ("Mature") in a target geography. For cell-level scoring that already incorporates business licenses as a signal, use the [Explorer](/locus/explorer); the dashboard is the raw record-by-record surface beneath the score. ## Filters [#filters] Every filter narrows the result set on the server side and resets pagination to the first page. Combine any subset of the filters below. | Filter | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Metro** | One or more metro slugs from the curated list (`chicago`, `philadelphia`, `nyc`, `denver`, `austin`, `portland`, `atlanta`, `los-angeles`, `san-francisco`, `seattle`, `houston`, `phoenix`, `las-vegas`, `miami`, `boston`). Multi-select; results match any of the selected metros. | | **Address** | Substring match (`ILIKE`) against the normalized `address` column. Useful for street, neighborhood, or partial address search. | | **NAICS code** | Substring match against `naics_code`. Enter a 2-, 4-, or 6-digit prefix to narrow by industry. | | **Pioneer tier** | One of `Pioneer`, `Advanced`, `Mature`, `Dormant`, or `None`. Distinguishes recently-issued licenses from long-running operators based on issue cadence and business age. | A **Reset filters** link clears every active filter in one click; it appears only when at least one filter is set. ## Sorting and pagination [#sorting-and-pagination] | Column | Default | Notes | | ---------------------------------- | ---------- | ------------------------------------------------------- | | **Loaded At** (`source_loaded_at`) | Descending | When Locus first ingested the record. The default sort. | | **Occurred At** (`occurred_at`) | — | When the licensing event happened upstream. | | **Metro** (`metro_slug`) | — | Alphabetical by metro slug. | Click any column header to sort by it; click the same header again to flip direction. The arrow indicator (`↑` / `↓`) marks the active sort. Results paginate at **50 per page** with a `Previous` / `Next` control and a running `Showing M–N of T` summary. ## Result columns [#result-columns] Each row in the table corresponds to one license record: * **Source ID** — the upstream license identifier. * **Metro** — the normalized metro slug. * **Address** — normalized street address (may be `—` if upstream is geocoded only). * **NAICS** — industry code if reported by the issuing jurisdiction. * **Pioneer tier** — color-coded badge (`Pioneer` / `Advanced` / `Mature` / `Dormant` / `None`). * **Loaded At** — ingestion timestamp, locale-formatted. * **Close Date** — license close or expiration date, when present. * **Maps icon** — opens the row's coordinates in Google Maps in a new tab. Shown only when both latitude and longitude are present. ## Export [#export] Click **Export CSV** in the top-right of the filter bar to download the **currently visible page** of results as `business-licenses.csv`. The export honors active filters and the current sort, and includes the column set: `Source ID, Metro, Address, NAICS, Pioneer Tier, Loaded At, Close Date`. The button is disabled when the result set is empty. To export more than 50 rows at a time, raise the page size by hitting [`GET /api/business-licenses/search?limit=200`](#api) directly — the API caps at 200 records per call but accepts arbitrary `offset` for follow-up pages. ## API [#api] The dashboard is a thin client over a single authenticated endpoint. ### `GET /api/business-licenses/search` [#get-apibusiness-licensessearch] Returns a page of normalized business licenses, plus the total count for the active filter set. **Query parameters** | Parameter | Type | Description | | -------------- | -------- | ------------------------------------------------------------------------ | | `metros` | `string` | Comma-separated metro slugs (e.g. `chicago,nyc`). | | `address_q` | `string` | Substring to match against `address`. | | `naics` | `string` | Substring to match against `naics_code`. | | `pioneer_tier` | `string` | Exact match — one of `Pioneer`, `Advanced`, `Mature`, `Dormant`, `None`. | | `sort_by` | `string` | One of `source_loaded_at` (default), `occurred_at`, `metro_slug`. | | `sort_dir` | `string` | `asc` or `desc` (default). | | `limit` | `number` | Page size. Default `50`, capped at `200`. | | `offset` | `number` | Zero-based offset for pagination. Default `0`. | **Response shape** ```json { "licenses": [ { "source_key": "chicago:1234567", "source_id": "1234567", "metro_slug": "chicago", "address": "123 N MAIN ST", "latitude": 41.8781, "longitude": -87.6298, "naics_code": "722511", "pioneer_tier": "Pioneer", "source_loaded_at": "2026-04-28T09:14:00Z", "close_date": null, "occurred_at": "2026-04-15T00:00:00Z" } ], "total": 1842, "limit": 50, "offset": 0 } ``` **Example** ```bash Find new restaurant licenses in Chicago and NYC curl 'https://app.axiomlocus.io/api/business-licenses/search?metros=chicago,nyc&naics=7225&pioneer_tier=Pioneer&limit=100' \ -H 'Cookie: ' ``` The endpoint requires an authenticated Locus session; unauthenticated calls return `401 Unauthorized`. ## Related [#related] Search zoning board appeal decisions across jurisdictions. Cell-level scoring that incorporates business-license activity as a signal. # Dashboard (/locus/dashboard) The Locus dashboard is the home screen for your workspace. It surfaces portfolio alerts, market pulse, and emerging signals, and includes a national **activity mini-map** that lets you jump straight into the [Explorer](https://app.axiomlocus.io/explore) at any location. ## National activity mini-map [#national-activity-mini-map] The mini-map is the shared `UnifiedMap` component running in **preview mode** — the exact same map core the [Explorer](/locus/explorer) uses, minus the filter, ranking, and selection controls. It renders the same `axiom_events` signal that powers the full Explorer, scoped to the last **90 days** across the contiguous United States, so the dashboard preview and the deep-dive read identically — same palette, same weight stops — and feel like one tool. Because the two surfaces share one map core, the dashboard heatmap uses the Explorer's activity paint (smaller radius, lower opacity, lighter color alphas than the previous dashboard-only palette). This is a deliberate UX convergence — the Explorer map is unchanged. ### What it shows [#what-it-shows] * **Heat density** — concentration of recent events (permits, civic, maritime, and other public-record signals) over the last 90 days. * **Event count** — total events in the visible window, shown in the top-left caption. * **Color ramp** — purple (low) → green → gold → orange (high), matched 1:1 with the Explorer map. ### How to use it [#how-to-use-it] ### Scan the country [#scan-the-country] The map opens fitted to CONUS so you can spot hot regions at a glance — corridors of permit activity, port congestion clusters, civic-record spikes. ### Click anywhere to score that location [#click-anywhere-to-score-that-location] Clicking a point opens the Explorer at that exact coordinate (`/explore?lat=…&lng=…`) with the score panel ready. No generic map view — you land where you clicked. ### Open the full Explorer [#open-the-full-explorer] Use the **Open Explorer** button in the top-right when you want the full-map workspace with filters, isochrones, and the cell sidebar. The mini-map is decorative when the activity feed is unavailable — your dashboard stat cards always render, even if the heatmap endpoint is degraded. ## Saved Searches [#saved-searches] The dashboard right rail includes a **Saved Searches** panel for re-running filter discoveries. It shows each saved search's name and saved date, and each row links to `/discover?saved=`. Use the panel's **New search** link to open `/discover`. When there are no saved searches, the panel directs you to save a discovery filter from `/discover`. ## Related [#related] Score a specific cell with live intelligence panels alongside the map. How signals roll up into cell scores. # APRS data standard (/locus/data-standards) APRS-normalized rows in the Axiom Locus data catalog carry a uniform set of metadata columns called the **APRS envelope** (AI-Ready Public Record Standard). The envelope makes it possible to deduplicate records, sync incrementally, cite sources, join across datasets, and feed data directly into ML pipelines. ## Envelope columns [#envelope-columns] The APRS envelope comprises these columns: | Column | Type | Description | | ----------------------- | ------------- | --------------------------------------------------------------------------------------- | | `record_id` | `text` | Stable URN for the source document. Format: `urn:aprs:record:{namespace}:{source}:{id}` | | `chunk_id` | `text` | Deterministic SHA-256 URN for vector indexing. Format: `urn:aprs:chunk:{hex}` | | `source_system` | `text` | Originating system name (e.g. `granicus`, `aisstream`, `derived`). | | `source_uri` | `text` | URL or URN pointing to the original upstream record. | | `schema_version` | `text` | Semver-tagged APRS profile (e.g. `aprs.civic/1.0.0`). | | `normalization_version` | `text` | Semver of the normalization pipeline that produced this row. | | `acl_tier` | `text` | Access tier: `research`, `commercial`, or `internal`. | | `occurred_at` | `timestamptz` | When the real-world event happened. | | `ingested_at` | `timestamptz` | When Axiom first ingested the record. | | `modified_at` | `timestamptz` | When the record was last updated in Axiom. | ## Schema profiles [#schema-profiles] Each data domain uses a versioned schema profile in `schema_version`: | Profile | Domain | | ----------------------- | ---------------------------------------------------- | | `aprs.civic/1.0.0` | Civic records (meeting minutes, ordinances, filings) | | `aprs.permits/1.0.0` | Building permits | | `aprs.events/1.0.0` | Axiom-curated events | | `aprs.urban/1.0.0` | Cell-level urban scores | | `aprs.maritime/1.0.0` | AIS positions and vessel visits | | `aprs.commodity/1.0.0` | Commodity prices, crop reports, and freight data | | `aprs.complaints/1.0.0` | 311 service requests | | `aprs.poi/1.0.0` | Points of interest | ## Domain-specific envelope extensions [#domain-specific-envelope-extensions] Some data domains extend the base envelope with additional indexed columns that are critical for their query patterns. These columns appear alongside the ten standard envelope columns and are tracked in the [envelope coverage dashboard](/codex/envelope-coverage). | Column | Type | Domain | Description | | ---------- | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `h3_index` | `text` | Geospatial tables | Uber H3 cell identifier at resolution 8. Enables spatial joins and cell-level scoring. | | `mmsi` | `text` | Maritime tables (`port_events`, `ais_positions`) | 9-digit Maritime Mobile Service Identity. Enables vessel-level joins and identity-spoofing detection. | Both columns are indexed and included in the `codex_compliance_summary` view as `h3_index_pct` and `mmsi_pct`. ## Record ID format [#record-id-format] Every `record_id` follows a deterministic URN pattern so the same real-world record always maps to the same identifier: ```text urn:aprs:record:{namespace}:{source_system}:{local_id} ``` For example: * `urn:aprs:record:civic:granicus:12345` — a civic record ingested from Granicus * `urn:aprs:record:maritime:vessel_visit:9434210:USLAX:7891` — a vessel visit keyed by IMO, port, and visit ID * `urn:aprs:record:commodity:conab:soy:2025/26:09:MT` — a crop report keyed by commodity, crop year, report month, and state ## Access tiers [#access-tiers] The `acl_tier` column controls data visibility: | Tier | Description | | ------------ | ----------------------------------------------------------- | | `research` | Publicly available data suitable for research and analysis. | | `commercial` | Licensed data available to commercial-tier subscribers. | | `internal` | Axiom-internal data not exposed through APIs. | ## Querying with envelope fields [#querying-with-envelope-fields] You can use envelope columns to filter, sort, and join across any Locus table. For example, to find recently ingested records from a specific source: ```sql select * from building_permits where source_system = 'socrata' and ingested_at > now() - interval '7 days' order by ingested_at desc limit 100; ``` To join records across tables by time window: ```sql select bp.record_id, cr.record_id from building_permits bp join civic_records cr on bp.occurred_at::date = cr.occurred_at::date and st_dwithin(bp.geom, cr.geom, 500) where bp.acl_tier = 'research'; ``` ## Compliance enforcement [#compliance-enforcement] Every change to collectors, edge functions, and migrations is validated against the APRS standard before it can be merged. The compliance pipeline runs three checks: 1. **Shape check** — verifies that every catalog table with data has envelope coverage tracked. If a table has rows but no `record_id` population metrics, the change is blocked. 2. **Runtime compliance** — samples the last 500 rows per table and validates them against nine APRS rules (valid URN format, non-null `source_uri`, valid timestamps, correct `acl_tier`, temporal ordering, and schema version format). Tables below 95% compliance with critical issues block the change. 3. **Static analysis** — flags collector files that write to catalog tables without importing the envelope function. This check is advisory and posts a warning rather than blocking. These checks run automatically — you do not need to trigger them. If you query Locus data through the API, every record you receive has passed these validations. ## Coverage [#coverage] The APRS envelope is present on all tables registered in the Locus data catalog. Envelope columns are populated automatically for new records at ingestion time. Historical records are being backfilled progressively — check `modified_at` to confirm a row has been fully normalized. ### Commodity tables [#commodity-tables] The following commodity and logistics tables carry the APRS envelope with the `aprs.commodity/1.0.0` or `aprs.maritime/1.0.0` profile: | Table | Namespace | Source | | ------------------------ | ----------- | -------------------------------- | | `antaq_vessel_calls` | `maritime` | ANTAQ (Brazil port authority) | | `conab_crop_reports` | `commodity` | CONAB (Brazil crop surveys) | | `antt_road_freight` | `commodity` | ANTT (Brazil road freight) | | `cepea_commodity_prices` | `commodity` | World Bank Pink Sheet | | `usace_lock_passages` | `maritime` | USDA Grain Transportation Report | ### Transit and vacancy tables [#transit-and-vacancy-tables] These sources have different APRS coverage in the current loaders: | Table | Namespace | Source | | --------------- | ----------------------- | ----------------------------------------------------------------- | | `ntd_ridership` | `infrastructure` | FTA National Transit Database (monthly xlsx from transit.dot.gov) | | `usps_vacancy` | — (not APRS-normalized) | HUD USPS Vacancy Data (quarterly, requires HUD registration) | The NTD loader writes all ten standard envelope columns — `record_id`, `chunk_id`, `source_system`, `source_uri`, `schema_version`, `normalization_version`, `acl_tier`, `occurred_at`, `ingested_at`, and `modified_at` — using the `aprs.infrastructure/1.0.0` profile. The current USPS vacancy loaders write only the domain columns shown in their table schema and do not populate APRS envelope columns; do not assume those rows have been normalized until a backfill or loader update is applied. # dbt marts (/locus/dbt-marts) Locus's analytics tables are built by a dbt-core project (`axiom_locus`) that transforms raw ingestion tables into typed, tested, APRS-compliant **marts**. Marts are the layer downstream consumers — the dashboard heatmap, Explorer, scoring service, and API — read from. Staging and intermediate models are internal scaffolding; only marts are part of the public contract. Locus uses **dbt-core** only. There is no dbt Cloud deployment. Local development materializes to DuckDB; production runs against the Locus Postgres database. ## Project layers [#project-layers] The `axiom_locus` dbt project has three model layers with fixed materializations: | Layer | Materialization | Purpose | | -------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `staging` | `view` | Thin, renamed views over raw source tables (`building_permits`, `nasa_firms_active_fires`, `cell_scores`). One staging model per source. | | `intermediate` | `ephemeral` | Reusable joins and rollups (e.g. `int_safety_signals_per_cell`). Compiled inline — never persisted. | | `marts` | `incremental` | Analytics-ready tables. Incremental by `ingested_at` watermark with `on_schema_change='append_new_columns'`. | Staging models normalize column names, cast types, and pass through the [APRS envelope](/locus/data-standards). Marts apply the `aprs_envelope` macro so every mart row carries `record_id`, `source_uri`, `source_system`, `schema_version`, `normalization_version`, `acl_tier`, `occurred_at`, `ingested_at`, and `modified_at`. ## Sources [#sources] The dbt project reads from three source tables in the `public` schema: | Source | Identifier | Owner | dbt usage | | ------------- | ------------------------- | --------------------------- | ------------------------------- | | `permits` | `building_permits` | Municipal permit collectors | Read-only via `stg_permits` | | `nasa_firms` | `nasa_firms_active_fires` | NASA FIRMS ingestion | Read-only via `stg_nasa_firms` | | `cell_scores` | `cell_scores` | Locus scorer service | Read-only via `stg_cell_scores` | `cell_scores` is **owned by the scorer service**. dbt reads it through `stg_cell_scores` but never writes to it. Do not point dbt models at `cell_scores` as a materialization target. ## `mart_axiom_events` [#mart_axiom_events] `mart_axiom_events` is the unified event surface for Locus. It is the same `axiom_events` signal the [dashboard heatmap](/locus/dashboard) and Explorer read from. Each row is one real-world event with H3-cell attribution and full APRS envelope. ### Configuration [#configuration] ```sql {{ config( materialized='incremental', unique_key='event_id', on_schema_change='append_new_columns' ) }} ``` * **Incremental** — only rows where `ingested_at` is newer than the current watermark are added on each run. * **Append-only** — `event_id` (an `md5` of `{source}:{record_id}`) is unique and stable. Re-running dbt is idempotent. * **Schema-evolution-safe** — new columns added to the model are appended to the table without rebuilds. ### Columns [#columns] | Column | Type | Description | | ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_id` | `text` | MD5 URN of `{source}:{record_id}`. Unique, stable across runs. | | `entity_id` | `text` | Logical entity the event applies to (e.g. `permit:123`, `h3:8828308281fffff`). | | `entity_type` | `text` | `permit`, `h3_cell`, etc. | | `entity_name` | `text` | Human-readable label. | | `event_type` | `text` | `permit.filed`, `permit.approved`, `permit.denied`, `permit.completed`, `fire.detected`. | | `event_category` | `text` | `development` or `safety_environment`. | | `h3_index` | `text` | H3 r8 cell ID. Always populated (rows without `h3_index` are filtered upstream). | | `magnitude` | `double precision` | Domain-specific magnitude: permit estimated cost, fire radiative power (FRP). | | `confidence` | `double precision` | 0.0–1.0 confidence in the event. Permit events use 0.70; FIRMS detections map `H/N/L` to `0.90/0.70/0.45`. | | APRS envelope | various | `record_id`, `source_uri`, `source_system`, `schema_version`, `normalization_version`, `acl_tier`, `occurred_at`, `ingested_at`, `modified_at` (see [APRS data standard](/locus/data-standards)). | | `metadata` | `json` | Source-specific extras, e.g. `{"source":"building_permits"}`. | ### Current event sources [#current-event-sources] Part A ships with two unioned sources: | Source | `event_type` values | `event_category` | | ------------------------- | ---------------------------------------------------------------------- | -------------------- | | `building_permits` | `permit.filed`, `permit.approved`, `permit.denied`, `permit.completed` | `development` | | `nasa_firms_active_fires` | `fire.detected` | `safety_environment` | Additional event sources land in Part B without changing the row shape — `on_schema_change='append_new_columns'` lets new columns appear without a rebuild. ### Querying [#querying] `mart_axiom_events` is a regular Postgres table — query it with any SQL client: ```sql -- Fire detections in the last 7 days, ranked by radiative power select event_id, h3_index, magnitude, confidence, occurred_at from mart_axiom_events where event_type = 'fire.detected' and occurred_at > now() - interval '7 days' order by magnitude desc limit 50; ``` Join to `cell_scores` to pull current scoring context for any event's cell: ```sql select e.event_id, e.event_type, e.occurred_at, cs.composite_score, cs.confidence as score_confidence from mart_axiom_events e join cell_scores cs using (h3_index) where e.event_category = 'development' and e.ingested_at > now() - interval '24 hours'; ``` ## The `aprs_envelope` macro [#the-aprs_envelope-macro] Every mart row carries the APRS envelope via a single macro call, so envelope shape is identical across sources: ```sql {{ aprs_envelope( source_system="'municipal_permits'", source_uri="'public.building_permits'", record_id_expr="'urn:aprs:record:locus:permit:' || coalesce(permit_id, source_id, 'unknown')", occurred_at_expr="coalesce(cast(issue_date as timestamp), ingested_at)", ingested_at_expr="ingested_at", modified_at_expr="modified_at", acl_tier="'research'" ) }} ``` Defaults: `schema_version='aprs.locus/1.0.0'`, `normalization_version='1.0.0'`, `acl_tier='research'`. Override per source when needed. ## Local development [#local-development] Install the dbt adapters into a Python environment: ```bash pip install dbt-duckdb dbt-postgres ``` Then build the project against DuckDB: ```bash cd packages/dbt-locus dbt deps dbt build --profiles-dir profiles --target dev ``` The `dev` target writes to `/tmp/axiom_locus.duckdb`. Use any DuckDB client to inspect compiled marts locally. ## Targets [#targets] The project ships three profiles: | Target | Adapter | Where it writes | | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `dev` | `duckdb` | Local `/tmp/axiom_locus.duckdb`. Used for iterative development. | | `ci` | `postgres` | Pull-request CI environment. Reads `DBT_POSTGRES_HOST`, `DBT_POSTGRES_USER`, `DBT_POSTGRES_PASSWORD`, `DBT_POSTGRES_DB`, `DBT_POSTGRES_PORT`. | | `prod` | `postgres` | Locus production Postgres. Same env vars as `ci`. | Both Postgres targets materialize into the `public` schema by default. ## Continuous integration [#continuous-integration] A GitHub Actions workflow runs `dbt deps && dbt build --profiles-dir profiles --target ci` on every pull request that touches the dbt project or the workflow file itself. The build executes every staging, intermediate, and mart model plus the `not_null` / `unique` schema tests defined in `models/marts/schema.yml`. PRs that break a model or fail a test are blocked at merge. Schema tests currently enforced on `mart_axiom_events`: * `event_id` — `not_null`, `unique` * `occurred_at` — `not_null` * `h3_index` — `not_null` ## Roadmap [#roadmap] Three marts are planned. Part A ships `mart_axiom_events`; the remaining two land in Part B without changes to the existing mart: * `mart_cell_score_composite` — replaces the in-app composite computation in the scorer service. * `mart_metro_overview` — replaces the hand-rolled metro overview SQL in the web service and retires the legacy `refresh_metro_overview` pg\_cron job. The full retirement plan for legacy pg\_cron event-source jobs runs in stages: land marts, parity-check against the existing pg\_cron-derived tables, migrate downstream consumers, then disable the pg\_cron jobs. # Explorer (/locus/explorer) The Explorer is where you go from "scan the country" to "score this exact location." The default layout puts the map next to an **Intelligence Rail** — a live feed of alerts, top movers, your monitored portfolio, and a market-pulse snapshot for the focused metro — so you don't lose dashboard context when you drill in. The Explorer and the [dashboard](/locus/dashboard) render the same map core (`UnifiedMap`), so the H3 grid, heatmap palettes, and hover behavior are identical between the two surfaces — the dashboard runs it in a read-only `preview` mode and the Explorer runs it in `explorer` mode with the full filter, ranking, hover, and selection loop wired in. ## Filters and weights [#filters-and-weights] The Explorer uses a **hybrid filter model**: hard gates decide which cells qualify for the current metro, and a weight vector across the eight [signal groups](/locus/scoring-conventions) ranks the survivors. Both live in the filter/weight panel — dragging any slider re-runs the ranking and repaints the map, the [Best-locations rail](#best-locations-rail), and the hover card together. ### Filters — gates to qualify [#filters--gates-to-qualify] Each of the eight signal groups (Business, Momentum, Demographics, Economic, Development, Accessibility, Safety, Amenity) plus the overall Composite has a **minimum-score gate** on a 0–100 slider. A cell must clear every non-zero gate to appear on the map or in the rail; a gate at `Any` (zero) is ignored. Use gates for hard requirements you'd never trade off — for example, "Safety ≥ 60 and Accessibility ≥ 40, or don't show it at all." The `confidenceMin` gate is on a **0–1 scale** (matching `cell_scores.confidence`), not 0–100. Values above 1 will filter every cell out. ### Weights — rank the survivors [#weights--rank-the-survivors] Weights are sliders per signal group that tell the ranker how important that dimension is to you. They are automatically normalized to sum to 1, so only the *ratios* matter — pushing "Business" from 20 to 40 while everything else is at 20 doubles its share regardless of the absolute number. Each qualifying cell gets a composite **Fit** score (0–100) equal to the weighted average of its group sub-scores under your current weights. The map's Fit heatmap and the Best-locations rail are both driven by this number. A default even weighting (`1/8` on every group) matches the standard composite. Adjust weights to bias the ranking toward what you actually care about — a retail siting weighting might zero out `development_pipeline` and push `amenity_demand` and `business_vitality` up. Under the hood the panel calls [`POST /api/cells/rank`](/locus/api/discovery-and-intelligence) with the current metro, gates, and normalized weights. The endpoint returns up to `2000` ranked cells per request (server-clamped, max `5000`). The client re-derives `fit` from the same weights so the map, the rail, and the ranker agree byte-for-byte. ## Best-locations rail [#best-locations-rail] Under the filter panel, the **Best-locations rail** lists the top 25 cells for the current filter + weight combination, ordered by Fit descending. Each row shows the rank, a truncated H3 index, and the Fit score color-coded against the standard [score palette](/locus/scoring-conventions). * **Hover a row** — highlights the same cell on the map with a glowing outline and shows the hover card. * **Click a row** — selects the cell (marker, radius ring, camera fly) exactly as if you had clicked it on the map. The left sidebar populates with the full score panel. The header reads `N shown` when 25 or fewer cells qualify and `Top 25 of N` when the qualified set is larger. If no cells clear the gates for the current metro, the rail prompts you to loosen a gate rather than silently rendering an empty list. ## Heatmap layers [#heatmap-layers] A layer picker above the map switches the whole cell-value paint between: | Layer | Source | What it shows | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | **Fit (weighted)** *(default)* | Client-computed from cell tile props and your current weights. | The composite Fit score under your current weight vector — the layer that reacts live as you drag weight sliders. | | **Composite** | `cell_scores.composite` | Baseline composite score, ignoring your weights. | | **Safety**, **Business** *(and any single [signal group](/locus/scoring-conventions))* | The named group column on `cell_scores`. | Raw sub-score for that one dimension. Useful for isolating a single driver before layering weights back in. | | **Crime** | [`GET /api/heatmap/crime`](/locus/api/analytics#get-apiheatmapdimension) | Raw H3 res-5 density of crime incidents. Not a score — treat it as an underlay. | The map legend below the layer picker is **layer-aware**: the title, ramp, and scale relabel between "score" (0–100 palette) and "density" (raw magnitude) so you can tell a normalized score from a raw count at a glance. `Fit (weighted)` is the default on load so every cell is visible and hoverable before you touch a filter or weight. The Best-locations rail fetches independently of the active layer — dragging filters or weights updates the rail whether or not the Fit heatmap is the layer you're looking at. ## Hover card [#hover-card] Hovering any cell on the map (or any row in the Best-locations rail) opens a compact hover card in the top-left of the map with: * The **Fit** score, color-coded and shown as a ring. * The **top driver** — the signal group with the highest sub-score for that cell — with its label and value (e.g. `Business vitality · 78`). Hovered and selected cells also get an outlined glow on the map so the rail row and the map cell always visually agree. ## Layout [#layout] The Explorer ships with two layouts. The default is **integrated**; **fullscreen** is a one-click fallback when you want the original map-first workflow. | Layout | When to use | How to switch | | -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Integrated (default) | Scoring a specific cell while keeping portfolio and market context visible. | Default on `/explore`. | | Fullscreen map | Pure map scanning — wide-area pattern recognition, demos, screenshots. | Click **Full map** in the top-right of the map, or visit `/explore?mode=fullscreen`. | The mode toggle lives in the top-right corner of the map and is visible in both layouts. Switching modes preserves all other URL parameters (lat, lng, filters, isochrones). ### Integrated mode [#integrated-mode] Three regions, left to right: * **Left sidebar** — cell-level score breakdown for the currently selected cell. Click a hex on the map to populate it. * **Map** — H3 grid, \~1/4 of the viewport width at `lg` (420 px), `xl` (520 px), and `2xl` (600 px) breakpoints. Resizes automatically when the window or layout changes. * **Intelligence Rail** — fills the remaining width with metro-level context. Independent of cell selection. ### Fullscreen mode [#fullscreen-mode] The rail is hidden and the map expands to fill the available space. The left sidebar with the cell breakdown stays visible. This matches the layout from before the integrated view shipped — use it when you just want to scan. ### Mobile and tablet [#mobile-and-tablet] Below the `lg` breakpoint (1024 px) the Intelligence Rail is hidden automatically and the map reverts to a flexible map-first layout. You can still open the cell sidebar by selecting a cell. ## Left sidebar [#left-sidebar] The left sidebar is anchored to the cell you have selected on the map. It surfaces information in priority order, with the highest-signal items pinned above the fold: * **Location header** — resolved place name and metro for the selected cell. * **Score panel** — composite score and the full per-signal breakdown for the cell. This is the canonical drill-in for *what does this score mean?* Each row in the breakdown's contribution waterfall is click-through: rows for the eight canonical [signal groups](/locus/scoring-conventions) (`business_vitality`, `population_momentum`, `demographics`, `economic_strength`, `development_pipeline`, `accessibility`, `safety_environment`, `amenity_demand`) link to the corresponding `/signals/[group]` detail subpage so you can dig into how that signal is computed without leaving the Explorer. Legacy or composite signal labels that have no detail page render as plain text. Each row also carries a small **freshness chip** showing how long ago the score was refreshed (for example, `2h`, `3d`, `5w`), color-coded against an SLA (see [Score freshness chips](#score-freshness-chips) below). The score-panel section header carries the same chip beside the title for a glanceable read of the cell's overall freshness. * **Score robustness badge** — a one-line "Stable core" / "Ambiguity shell" / "Stable (low)" label that tells you whether the composite score above survives a grid-resolution change. Renders the cell's [consensus class](/locus/scoring-conventions#per-cell-consensus-class) with a percent-agreement score (for example, *Stable core · 92% support agreement*); hover for the full explanation. Hidden when the cell has not yet been classified. * **Nearby intelligence summary** — at-a-glance badges that count the eateries, services, recreation, and retail amenities within the cell's neighborhood. Renders without a click. * **Crime safety** — a one-line safety read for the cell, sourced from the same data that feeds the Safety & Environment signal. * **Nearby POIs** — a collapsible accordion of every individual point of interest within range, with photos, distance, type, and an expander for per-POI detail (address, phone, website, Google Maps link). * **Look-alike cells** — a compact list of the cross-metro nearest cells to the selected one, with a **By score ↔ By satellite signature** toggle. See [Look-alike cells](#look-alike-cells) below. The **Nearby POIs** accordion is collapsed by default. POI is a supporting due-diligence detail, not a primary nav element — the **Nearby intelligence summary** and **Crime safety** above it carry the headline counts and the safety read without requiring a click. Click the row labelled **Nearby POIs** (it shows the count, e.g. *15 shown*) to expand the full list, and click again to collapse it. ### Score freshness chips [#score-freshness-chips] Every row of the contribution waterfall carries a small relative-age chip (`now`, `5m`, `2h`, `3d`, `5w`) showing how long ago the cell's signals were last refreshed. The same chip renders next to the score-panel section header so the freshness picture is readable at a glance, before any drilling. Chips are color-coded against the score-refresh SLA: | Tone | Age | Meaning | | ----- | --------------------------- | -------------------------------------------------------------------------------------------- | | Dim | ≤ 72 hours | **Fresh.** The score reflects the current data window. | | Amber | 72 – 168 hours (3 – 7 days) | **Aging.** Refresh is pending; treat the score as directional. | | Red | > 168 hours (> 1 week) | **Stale.** The score has missed at least one refresh window — re-score before relying on it. | Hover any chip to see the absolute refresh timestamp and its readable status (for example, *Last refreshed Apr 27, 2026, 9:14 AM · aging (>3 days)*). All eight signal groups currently share a single refresh snapshot — `score_history` updates atomically per cell, so per-row chips on the same cell display the same age. The chips are repeated on every row deliberately: it makes freshness un-missable when scanning the waterfall, and reserves the per-row slot for a future per-signal differential refresh without changing the layout. The cell's coarser **staleness tier** in the score-panel footer (`prime` / `stale` / `unscored`) is a separate, longer-window annotation and is unchanged. The freshness chips described here are a finer-grained per-refresh indicator, not a replacement for the tier. ### Look-alike cells [#look-alike-cells] The **Look-alike cells** panel surfaces the cross-metro nearest cells to the currently selected one, ranked by *driver-profile* similarity rather than by absolute composite distance. It is designed to answer "where else does a place like this exist?" — an intent the legacy same-metro *Comparable cells* card (still shown alongside) cannot address, because that card only compares cells inside the same metro by `|Δcomposite|`. Each row shows the neighbor's metro, its H3 index, a similarity percentage (`0–100%`, where `100%` is an identical driver profile), and the neighbor's composite score. The panel is backed by [`POST /api/cells/similar`](/locus/api/discovery-and-intelligence#post-apicellssimilar) and exposes the endpoint's `mode` as a two-option toggle: | Toggle | Mode | What it compares | | -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **By score** (default) | `score` | The 8-d cell score profile — the eight [signal groups](/locus/scoring-conventions). Two cells match when their signal mix looks alike, regardless of overall composite level. | | **By satellite signature** | `satellite` | A 64-d AlphaEarth satellite embedding — built form, greenness, land cover. Independent of the score. | Score mode works today; the satellite embedding is still being backfilled, so **By satellite signature** currently renders `No satellite embedding for this cell yet.` for cells without an embedding. Switching the toggle re-fetches the panel — expect a brief loading state. Errors from the endpoint fall back to `Could not load look-alikes.` rather than tearing down the cell detail panel. ## Intelligence Rail [#intelligence-rail] The rail surfaces the same data that powers the [dashboard](/locus/dashboard), scoped to the metro you're currently viewing. It refreshes when the page loads. The rail has two modes that flip automatically based on whether a cell is selected on the map: * **Metro default** — no cell selected. All monitors and alerts in scope. Header subtitle reads `Live signal feed for the current map`. * **Cell context** — a hex is selected. A Selected-cell panel pins to the top of the rail and the Portfolio section filters to the active metro. Header subtitle reads `Cell selected · {METRO} context`. The cell-level *score breakdown* still lives in the left sidebar's score panel. The rail surfaces metro context around the selection rather than duplicating cell internals. ### Selected cell [#selected-cell] Appears at the top of the rail when a hex is picked on the map. Anchors the rail's metro context to the active cell with three glanceable visualizations: * **Header** — location name (or lat/lng), composite score with tier color, and the metro plus a truncated H3 index. * **90-day trajectory** — a compact SVG sparkline of the cell's composite score over the last 90 days. The stroke is trend-colored: emerald when the score is rising, red when declining, and dim when flat. When the underlying data is a synthetic flat-trend stand-in for a cell with no real history, the line renders dashed at reduced opacity and the label reads `90-day trajectory (estimated)` so you can tell estimated lines from real measurements. Hidden when fewer than two snapshots are available. * **Signal contribution** — a horizontal-bar waterfall of the cell's eight [signal groups](/locus/scoring-conventions), sorted by score so the strongest signals lead. Each bar is tier-colored (the same palette as composite scores) with the rounded score on the right. Groups with confidence below 0.4 render dim with a tooltip that names the underlying coverage gap (for example, `Low confidence (28%) — limited source coverage`), so a high score backed by sparse data is visually distinguishable from a confident one. Together, the three replace the previous "what does the composite mean?" narrative with a comparison the user can read at a glance. The full cell-level breakdown — every sub-signal under each group — still lives in the left sidebar's score panel for users who want to drill in. ### Metro key stats [#metro-key-stats] A three-up strip of synchronous metro stats that renders without a network round-trip: | Stat | Source | | ---------- | ----------------------------------------------------------------------------------------------------------------- | | Composite | Average of the metro's eight signals. | | GDP YoY | Year-over-year GDP growth, color-coded green for positive and red for negative. | | Top signal | The highest-scoring signal for the metro, surfacing what's actually strong about it instead of dumping all eight. | ### Safety tier distribution [#safety-tier-distribution] A stacked-bar visualization directly under the key stats showing how the metro's scored cells distribute across five safety tiers — **Prime** (≥80), **Strong** (60–79), **Solid** (40–59), **Watch** (20–39), and **Elevated** (below 20). Each segment's width is proportional to the share of cells in that tier, and the legend below the bar lists exact counts. The view answers "is this metro mostly safe, or mostly elevated?" without leaving the page. The bar is backed by [`GET /api/metro-tier-distribution`](/locus/api/discovery-and-intelligence#get-apimetro-tier-distribution) and defaults to the `safety_environment` signal. The same component can render distributions for any [signal group](/locus/scoring-conventions) (development pipeline, business vitality, composite) by passing a different `signal` prop — useful when embedding in custom dashboards. ### Recent alerts [#recent-alerts] Score changes on locations in your portfolio over the last scoring window, ordered by recency. Each row links to `/monitors` for the full history. ### Top movers [#top-movers] The four largest absolute score swings from the recent-alerts pool — the locations whose intelligence picture moved most, regardless of direction. ### Portfolio [#portfolio] Your monitored locations, with their latest score color-coded: * **Green** — score ≥ 70 * **Cyan** — score 50–69 * **Amber** — score \< 50 * **Dim** — no score yet Click any row to jump the map to that location. In cell-context mode the list filters to the metro of the selected cell — the subtitle reads `{N} in {METRO}` and the empty state explains why (`No monitored locations in {METRO} yet. Click any cell to add one.`). ### Market Pulse [#market-pulse] A snapshot of the focused metro: composite score, population growth, development pipeline, and a short narrative. Click through for the full Pulse page. ### Development Pipeline permit trend [#development-pipeline-permit-trend] Below **Market Pulse**, the Intelligence Rail has a separate **Development Pipeline** section with a 12-month permit-issuance chart for the focused metro. It is not part of the Market Pulse card. If permit data is unavailable for the focused metro, the section shows a "No permit data for this metro" note instead of the chart. Recent alerts and Portfolio pull from `/api/alerts/history` and `/api/monitors` — the same endpoints the dashboard uses. If those endpoints are unavailable the rail shows empty states instead of failing the page. The Selected-cell panel, Metro key stats, and Market Pulse render from local data and never make a network call. The rail and the dashboard render the same alert, monitor, and metro-pulse markup from a shared component set, so copy and styling stay in sync between the two surfaces. ## URL parameters [#url-parameters] The Explorer supports deep links via query string. Combine these to land users in a specific view. | Parameter | Values | Description | | --------- | ---------------------------------- | ------------------------------- | | `lat` | number | Latitude to center the map on. | | `lng` | number | Longitude to center the map on. | | `mode` | `fullscreen` (omit for integrated) | Force fullscreen layout. | ```text Deep link to a cell in fullscreen mode https://app.axiomlocus.io/explore?lat=40.7128&lng=-74.0060&mode=fullscreen ``` ```text Default integrated layout at the same coordinates https://app.axiomlocus.io/explore?lat=40.7128&lng=-74.0060 ``` ## Related [#related] The national overview that feeds into the Explorer. How signals roll up into the cell scores you see in the sidebar. # Get started with Locus (/locus/getting-started) Axiom Locus is a location intelligence platform that scores every neighborhood in the United States using 30+ public data sources — building permits, employment data, business openings, crime statistics, environmental risk, and more. Scores are computed on [Uber's H3 hexagonal grid](https://h3geo.org/) at \~460 m resolution, giving you a consistent, comparable picture of any market. In this guide you'll create a workspace, score your first cell, and export your findings.

Axiom Locus location score report showing a composite score of 78.4, confidence, and horizontal bars for eight signal groups such as safety, business vitality, and competitive density

## Prerequisites [#prerequisites] * A work email address (Locus workspaces are team-scoped) * A market or location in mind — a city, zip code, or address you want to evaluate ### Create your workspace [#create-your-workspace] Sign up at [app.axiomlocus.io](https://app.axiomlocus.io). Your workspace includes a default scoring profile (`general`) tuned for commercial real estate analysis. You can switch profiles later for use-case-specific weighting (QSR, retail, office, industrial, data center, self-storage). ### Pick a market [#pick-a-market] From the [dashboard](/locus/dashboard), scan the national activity mini-map — a 90-day heatmap of permits, civic records, and other public signals across the contiguous US. Type a city or zip code in the search bar, or click anywhere on the mini-map to drop into the Explorer at that point. Locus loads the H3 cell grid for the area. Each hexagon represents roughly 0.74 km² (about a census block group) and carries its own composite score. ### Score and filter [#score-and-filter] In the Explorer, open the **Cells** panel. Pick the signals you care about — development pipeline, economic strength, business vitality, safety, accessibility — and Locus ranks every cell in your view by the selected profile. Click any cell to open its **score breakdown**: the composite score (0–100), per-signal-group sub-scores, the data sources used, and any sources that are missing for that location. The breakdown tells you not just *what* a cell scored, but *why* — and how confident the score is given data availability. ### Export and share [#export-and-share] Use the **Export CSV** button in the Cells panel to download a spreadsheet of every scored cell in your view, including sub-scores and confidence intervals. Share the Explorer view with teammates via a workspace link — they'll see the same map, filters, and cell selection. ## What you'll see [#what-youll-see] The Explorer is your primary workspace. It combines: | Panel | What it shows | | ----------------------- | ------------------------------------------------------------------------------------------ | | **Map** | H3 cell grid color-coded by composite score, with the underlying signal heatmap toggleable | | **Cell sidebar** | Ranked list of cells in view, sortable by any signal group | | **Score breakdown** | Per-cell detail: composite, sub-scores, weights, sources used/missing, confidence | | **Intelligence panels** | Contextual data for the selected cell — permits, businesses, crime, environmental risk | ## Next steps [#next-steps] How signals roll up into cell scores — weights, profiles, sub-scores, and confidence semantics. The APRS envelope, normalization pipeline, and dataset catalog behind every signal. Full guide to the Explorer workspace — filters, isochrones, and cell comparison. The analytics layer that transforms raw signals into scoring-ready features. Locus scores are recomputed nightly. Each cell carries a staleness tier that reflects how recently its underlying signals were refreshed — see [scoring conventions](/locus/scoring-conventions) for the freshness commitments. # Axiom Locus (/locus) Sign up and explore your first territory. Product overview, datasets, and case studies. Seeded workflows ## Choose a decision surface [#choose-a-decision-surface] Three flagship workflows show how Axiom Locus turns public signals into explainable territory intelligence. The linked demos use deliberately seeded samples for product conversations—not live customer data. Surface site-readiness friction before a trial network commits to a metro. Give operations teams an explainable watchlist for permits, inspections, and nearby exposure. Catch early public signals around capital plans, zoning changes, and future procurement. ## How a cell is scored [#how-a-cell-is-scored] Ready to evaluate a territory? Start with [getting started](/locus/getting-started), or email [support@axiomancer.io](mailto:support@axiomancer.io) for help choosing a demo or planning a tailored walkthrough. Locus ships weekly release notes in the [changelog](/changelog). # MCP server (/locus/mcp-server) The Axiom MCP server exposes location scoring, building permits, metro rankings, government procurement data, and maritime intelligence to any LLM that supports the [Model Context Protocol](https://modelcontextprotocol.io). Use it to query Axiom data through natural language in tools like Claude Desktop, Cursor, or any MCP-compatible client. ## When to use the MCP server [#when-to-use-the-mcp-server] Use the MCP server when you want to: * Ask an LLM questions about location scores, permit activity, or market trends without writing API calls * Build AI-powered workflows that pull real-time CRE or maritime intelligence * Let analysts interact with Axiom data conversationally ## Prerequisites [#prerequisites] * Node.js 18 or later * An Axiom Locus API key (get one at [app.axiomlocus.io](https://app.axiomlocus.io)) * An MCP-compatible client (Claude Desktop, Cursor, or similar) ## Installation [#installation] Install the MCP server package: ```bash npm install axiom-mcp-server ``` Or run it directly: ```bash npx axiom-mcp-server ``` ## Configuration [#configuration] The server reads configuration from environment variables: | Variable | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------ | | `AXIOM_LOCUS_API` | No | Locus API base URL. Defaults to `https://axiomlocus.io`. | | `AXIOM_LOCUS_API_KEY` | Yes | Your Locus API key for authenticated endpoints. | | `LOCUS_SUPABASE_URL` | No | Direct Supabase URL for discovery and ranking queries. Falls back to `NEXT_PUBLIC_SUPABASE_URL`. | | `LOCUS_SUPABASE_KEY` | No | Supabase service key. Falls back to `SUPABASE_SERVICE_KEY`. | | `OVERWATCH_SUPABASE_URL` | No | Enables maritime intelligence tools when set. | | `OVERWATCH_SUPABASE_KEY` | No | Supabase key for Overwatch data. | ### Claude Desktop [#claude-desktop] Add the server to your Claude Desktop configuration file: ```json { "mcpServers": { "axiom": { "command": "npx", "args": ["axiom-mcp-server"], "env": { "AXIOM_LOCUS_API_KEY": "your-api-key" } } } } ``` ### Cursor [#cursor] Add the server in your Cursor MCP settings: ```json { "mcpServers": { "axiom": { "command": "npx", "args": ["axiom-mcp-server"], "env": { "AXIOM_LOCUS_API_KEY": "your-api-key" } } } } ``` ## Available tools [#available-tools] The MCP server exposes the following tools to connected LLMs. ### Locus tools [#locus-tools] These tools provide location intelligence across 22 US metros. | Tool | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `axiom_score_location` | Score any location across 8 signal groups. Returns composite score (0--100), tier label, confidence, and per-group breakdown. Supports scoring profiles: `general`, `qsr`, `retail`, `office`, `self_storage`, `data_center`, `industrial`. | | `axiom_discover_locations` | Filter locations by metro, composite score range, and individual signal group minimums. | | `axiom_get_rankings` | Curated top-25 lists. Public lists (free, sourced from verifiable third-party data, rendered in full to all callers): `fastest-growing-population` (U.S. Census ACS 5-year estimates; tracts with fewer than 1,000 prior residents are excluded so small-denominator anomalies don't dominate), `most-building-permits` (municipal permit databases, last 12 months). Composite-tier lists (Axiom Composite Score) — preview the top 3 rows for free or signed-out callers and return the full top 25 on **Analyst** ($49/mo) or higher (Pro, Team, Enterprise, Supply Chain Risk): `top-overall`, `fastest-growing`, `safest-urban`, `most-business-active`, `best-for-restaurants`, `strongest-economies`, `best-accessibility`, `development-hotspots`. The preview cap is enforced server-side in `getRankingResults()`, so locked rows are never returned to unauthenticated tools. | | `axiom_search_permits` | Search building permits by metro, with optional date filter. Returns permit type, status, address, and estimated cost. | | `axiom_get_council_decisions` | City council decisions on rezoning, variances, conditional use, site plans, and demolitions. Captures development intent months before permits are filed. | | `axiom_get_metro_pulse` | Market intelligence for a metro: average signal group scores across all scored cells. | | `axiom_list_metros` | List all 22 tracked US metros with slugs. | | `axiom_nearby_intelligence` | Everything known about a location across all data types: permits, POIs, schools, council decisions, clinical trials, FDA events, OSHA, EPA, zoning, and NIH grants. | | `axiom_get_score_trends` | Historical score trends for a metro or specific H3 cell over a configurable lookback period. | | `axiom_get_clinical_trials` | Clinical trial facility data filtered by state, sponsor, or phase. | | `axiom_get_zoning` | Zoning district rules: allowed uses, height limits, FAR, setbacks, and parking requirements. | | `axiom_get_school_ratings` | K-12 school quality ratings, enrollment, and student-teacher ratios near a location. | | `axiom_get_weather` | Current weather observations from personal weather stations near a location. | | `axiom_get_weather_station` | Weather data from a specific station by ID. | | `axiom_search_bids` | Government bid and procurement opportunities from SAM.gov, filtered by state, keyword, NAICS code, or bid type. | | `axiom_get_bid_detail` | Details for a specific government bid by notice ID. | ### Overwatch tools [#overwatch-tools] These tools are available when `OVERWATCH_SUPABASE_URL` and `OVERWATCH_SUPABASE_KEY` are configured. | Tool | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `axiom_track_vessel` | Track a vessel by IMO, MMSI, or name. Returns details, risk score, and port call history. | | `axiom_get_positions` | Latest AIS vessel positions at a grain export port. | | `axiom_get_export_estimates` | Weekly grain/commodity export tonnage estimates derived from vessel draft changes. | | `axiom_get_congestion` | Port congestion index: vessels waiting, median wait times, and trends. | | `axiom_get_risk_vessels` | Vessels ranked by 13-factor risk score, including dark fleet and sanctions factors. | | `axiom_get_dark_events` | AIS transmission gap events with risk scoring and proximity to ship-to-ship transfer hotspots. | | `axiom_get_trade_flows` | Bilateral commodity trade flow data from UN Comtrade. | | `axiom_get_mirror_discrepancies` | Cases where exporters and importers report different volumes for the same commodity pair. | | `axiom_get_sanctioned_vessels` | Vessels matched against OFAC sanctions via IMO, MMSI, or name-based entity resolution. | | `axiom_get_commodity_prices` | Commodity price data for wheat, corn, soybeans, crude oil, and more. | | `axiom_list_ports` | All 34 grain export ports monitored by Overwatch. | | `axiom_get_disruptions` | Real-time disruption signals from GDELT: port closures, sanctions, trade disputes, weather events. | | `axiom_get_river_levels` | Real-time USGS river water levels for waterways critical to grain barge transport. | | `axiom_get_alerts` | Active platform alerts: sanctions matches, river level warnings, dark fleet events. | | `axiom_check_sar_coverage` | Check whether the Sentinel-1 catalog lists imagery near a location and time for an independent investigation. Catalog coverage does not verify a vessel or dark-fleet event. | ## Example prompts [#example-prompts] Once the MCP server is connected, you can ask your LLM questions like: * "Score the location at 35.2271, -80.8431 for a QSR site" * "Show me the top 25 fastest-growing locations across all metros" * "What building permits were filed in Charlotte in the last 30 days?" * "What council rezoning decisions happened in Austin recently?" * "Find locations in Miami with a composite score above 80 and strong business vitality" * "Are there any government bids for construction in Texas?" * "What's the current weather near 37.7749, -122.4194?" With Overwatch configured: * "Track vessel IMO 9321483" * "What's the congestion like at the port of Santos?" * "Show me dark fleet events in the last week" * "What are the current river levels on the Mississippi?" # Scoring conventions (/locus/scoring-conventions) This page documents the contracts that shape every Locus scoring response. It complements the [APRS data standard](/locus/data-standards) — that page covers the underlying record envelope; this page covers the API-surface scoring semantics. ## H3 cell index [#h3-cell-index] Locus uses [Uber's H3 hierarchical hexagonal grid](https://h3geo.org/) for spatial indexing. Every score, metric, and POI lookup resolves to an H3 cell. ### Resolution [#resolution] | Resolution | Edge length (km) | Use case | | ---------- | ---------------- | ----------------------------------------------------- | | **6** | 3.7 | Metro-level summaries (San Francisco, Chicago) | | **8** | 0.46 | Neighborhood-level scoring (default for `/api/score`) | | **9** | 0.17 | Block-level analysis (high-res scoring profiles) | The default scoring resolution is **H3 r8** — about 0.46 km hex edge, which roughly corresponds to a "block group" in US census terms. You can request higher resolution via the `radius` parameter — Locus aggregates child cells appropriately. ### Per-metro resolution overrides [#per-metro-resolution-overrides] Some low-density, large-parcel metros are scored at **H3 r7** (\~5.16 km², \~1280 m radius) instead of the default r8 (\~0.74 km², \~490 m radius). At r8 a single cell in these markets often covers only one CRE asset, which leaves signal aggregation dominated by small-n noise. Coarsening to r7 produces enough samples per cell for the score to be statistically meaningful. Metros currently overridden to r7: * Phoenix * Houston * Las Vegas * Dallas * San Antonio * Nashville * Jacksonville * Oklahoma City * El Paso * Fort Worth Every other metro continues to score at the r8 default. The override is additive — historical scores are unaffected and no migration is needed on your side. Each row written to `cell_scores` is tagged with the resolution it was computed at via the `resolution_variant` column, so downstream consumers (rankings, MAUP ensembles, the explorer) can distinguish r7 from r8 cells. If you join scores across metros, filter or group on `resolution_variant` rather than assuming a single resolution. ### Cell IDs in API responses [#cell-ids-in-api-responses] Cell IDs are the standard 15-character hex strings produced by `h3-js` (e.g. `8828308281fffff`). Use these as opaque identifiers when caching scores client-side; Locus pins the H3 algorithm version and won't change cell-ID semantics without a major API version bump. ## Scoring profiles [#scoring-profiles] The `profile` parameter on `/api/score` adjusts signal weights for a use case. Each profile is a fixed weighting — Locus does not auto-tune weights from your historical data (custom-tuned profiles are on the roadmap). | Profile | Top-weighted signals | Underweighted signals | | -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `general` | Development pipeline (permits), economic strength (employment, GDP), accessibility (transit) | Amenity demand, demographics, population momentum | | `qsr` | Foot traffic, demographics (income), competitor density | Permits, real estate | | `self_storage` | Population density, housing turnover, road accessibility | Foot traffic, business vitality | | `retail` | Foot traffic, parking availability, complementary tenants | Jobs, permits | | `office` | Transit access, daytime population, business vitality | Demographics (residential), traffic | | `data_center` | Broadband, power infrastructure, environmental risk, accessibility | Amenity demand, business vitality | | `industrial` | Road accessibility, workforce availability, zoning, economic strength | Amenity demand, demographics (residential) | Composite scores are 0–100 with a documented confidence interval. Sub-scores per signal group are also 0–100. ### `general` profile weights [#general-profile-weights] The `general` profile is tuned for generic commercial real estate (CRE) price prediction rather than any specific use case. Weights are calibrated against the empirical CRE price-correlation literature — building permit issuance, employment density change, and transit ridership are the three signals with the strongest published correlations and clearest lead times against CRE prices. | Signal group | Weight | Rationale | | --------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | `developmentPipeline` | 0.20 | Building permit issuance has R² ≈ 0.55 against CRE prices on a 6–12 month lead (Conference Board LEI). | | `economicStrength` | 0.20 | Employment density change (LEHD) shows strong correlation with retail and office CRE on a 3–9 month lead. | | `businessVitality` | 0.15 | Establishment counts and payroll trends — directional but less validated than the top two. | | `accessibility` | 0.12 | Transit ridership shows positive correlation with walkable commercial CRE on a 12–24 month lead. | | `populationMomentum` | 0.10 | Migration and population change — long-lead but noisier in short windows. | | `demographics` | 0.10 | Income, age mix, and education — slow-moving baseline, not a short-term price driver. | | `safetyEnvironment` | 0.08 | Crime is the peer-reviewed safety predictor; flood and environmental risk feed in as constraints. | | `amenityDemand` | 0.05 | Schools, food access, and retail amenities — important for residential but a weak signal for generic CRE. | Use a use-case profile (`qsr`, `office`, `industrial`, `retail`, `data_center`, `self_storage`) when you have a specific tenant or asset class in mind — those weights reflect industry-specific priorities rather than generic price prediction. The use-case profile weights are unchanged from prior `general` rebalances. ## Development pipeline sub-scores [#development-pipeline-sub-scores] The `developmentPipeline` group rolls up several permit- and construction-derived sub-signals. Each `subScores` entry returned in the API response carries a `name`, a 0–100 `score`, a `weight`, and a `source` label. | Sub-score | Weight | Source | What it measures | | ---------------------- | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Permit Activity | 0.40 | Building Permits | Cell-level permit count and total declared valuation over the trailing 6 months. Falls back to metro-wide averages when the cell itself has zero permits. | | Construction Detection | 0.20 | Sentinel-2 | Satellite-derived change-detection score for active construction footprints. | | Land Cover Change | 0.20 | NLCD | Year-over-year change in the share of developed land cover. | | Opportunity Zone | 0.10 | Federal OZ | Binary flag for federal Qualified Opportunity Zone designation. | | Permit Velocity | 0.05 | Building Permits Trend | Acceleration or deceleration in permit issuance vs. the prior 6-month window. | | Permit Volatility | 0.05 | Building Permits Volatility | Run-to-run variance in permit issuance; high volatility lowers the sub-score. | | Permit Valuation Tier | 0.10 | AXL-5 | LLM-classified valuation tier (`transformative`, `structural`, `stabilization`) for the dominant permit mix in the cell. | | Permit Scope Quality | 0.10 | AXL-108 | Per-permit `scope_type` × `cost_tier` quality signal — see below. | ### Permit Scope Quality (AXL-108) [#permit-scope-quality-axl-108] `Permit Scope Quality` weights every permit in the trailing 6-month window by what the permit is for, not just how many were issued. Each permit's `scope_type` and `estimated_cost_tier` — both extracted by an LLM-based permit classifier from the free-text description — are multiplied to yield a 0–100 contribution, and the cell's sub-score is the average of those contributions across the window. **Scope-type weights:** | `scope_type` | Weight | | ------------------ | ------ | | `new_construction` | 1.0 | | `addition` | 0.7 | | `demolition` | 0.5 | | `renovation` | 0.3 | | `repair` | 0.1 | **Cost-tier multipliers:** | `estimated_cost_tier` | Multiplier | | --------------------- | ---------- | | Tier 1 (highest) | 1.5 | | Tier 2 | 1.0 | | Tier 3 | 0.5 | | Tier 4 (lowest) | 0.25 | A cell dominated by `new_construction` permits in the highest cost tier will trend toward 100; a cell dominated by low-cost `repair` permits will trend toward 0. The signal is designed to separate cells where permits indicate genuine new development from cells where permits mostly reflect maintenance churn. When the LLM extractor has not yet annotated any permit in a cell, the sub-score is omitted from `subScores` and `AXL-108` appears in `sourcesMissing` for the group. ```json { "developmentPipeline": { "score": 71.4, "subScores": [ { "name": "Permit Activity", "score": 78, "weight": 0.40, "source": "Building Permits" }, { "name": "Permit Scope Quality", "score": 64, "weight": 0.10, "source": "AXL-108" } ], "sourcesUsed": ["Building Permits", "AXL-108"], "sourcesMissing": [] } } ``` ## Safety & environment sub-scores [#safety--environment-sub-scores] The `safetyEnvironment` group rolls up crime, regulatory hazard maps, realized loss history, environmental burden, air quality, and 311 service-request signals. | Sub-score | Weight | Source | What it measures | | -------------------------- | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Crime Rate | 0.30 | Local Police | Reported incidents per 1k residents in the trailing window. | | Flood Risk | 0.20 | FEMA | Forward-looking FEMA FIRM flood-zone designation (`X`, `A`, `AE`, `V`, etc.). | | Flood Loss History | 0.15 | AXL-109 (FEMA NFIP) | Realized NFIP claim history for the cell's nearest zip — see below. | | Environmental Risk | 0.15 | EPA EJScreen | Composite EJ index (pollution + demographic burden). | | Natural Hazard Risk | 0.15 | FEMA NRI | National Risk Index composite for 18 natural hazard types. | | Air Quality | 0.10 | EPA AirNow | Trailing AQI exposure. | | Complaint Density | 0.05 | 311 Service Requests | Open-complaint volume per cell. | | Complaint Velocity | 0.05 | 311 Service Requests Velocity | 30-day change in complaint volume. | | Resolution Time | 0.05 | AXL-6 | Average days-to-close for 311 complaints in the cell. | | Complaint Trend YoY | 0.05 | AXL-107 (311 YoY) | Year-over-year delta on the cell's trailing 30-day 311 complaint density — see below. | | Utility Complaint Density | 0.04 | ICC | Illinois Commerce Commission utility-service complaint volume at the cell's nearest zip — see below. | | Nuclear Facility Proximity | 0.05 | NRC | Distance in km from the cell to the nearest NRC-licensed reactor site, scaled against NRC emergency-planning-zone radii — see below. | ### Flood Loss History (AXL-109) [#flood-loss-history-axl-109] `Flood Loss History` is a realized-loss companion to the regulatory FEMA FIRM `Flood Risk` sub-score. The two signals answer different questions: * **Flood Risk** — *What does the regulatory map say this cell is?* Forward-looking, redrawn on a multi-year cycle. * **Flood Loss History** — *What has actually happened here?* Backward-looking, derived from FEMA National Flood Insurance Program (NFIP) claims. This distinction matters because repeat-loss corridors and flash-flood-prone areas frequently sit in non-`A`/`V` FIRM zones — the FIRM map is a snapshot of modeled hazard, while NFIP claims capture realized loss patterns including pluvial flooding, drainage failures, and stormwater backups that the FIRM zone often misses. The sub-score is computed by: 1. Finding the nearest US zip centroid to the cell (single PostGIS nearest-neighbor lookup). 2. Joining that zip to the aggregated NFIP claims table (677k+ raw claims rolled up to \~17.8k zip-level records). 3. Returning a normalized exposure score in `[0, 1]` derived from claim count, repeat-loss policy share, and the most recent claim year. 4. Inverting to a 0–100 safety contribution: a zip with no historic claims scores 100, a maximum-exposure zip scores 0. When the cell's nearest zip has no NFIP claims (common for inland low-risk geographies), the sub-score is omitted from `subScores` and `AXL-109 (FEMA NFIP)` appears in `sourcesMissing` for the group. NFIP coverage is US-only — international cells will always show this source as missing. ```json { "safetyEnvironment": { "score": 64.2, "confidence": 0.83, "subScores": [ { "name": "Crime Rate", "score": 72, "weight": 0.30, "source": "Local Police" }, { "name": "Flood Risk", "score": 80, "weight": 0.20, "source": "FEMA" }, { "name": "Flood Loss History", "score": 78, "weight": 0.15, "source": "AXL-109 (FEMA NFIP)" }, { "name": "Environmental Risk", "score": 61, "weight": 0.15, "source": "EPA EJScreen" } ], "sourcesUsed": ["Local Police", "FEMA", "AXL-109 (FEMA NFIP)", "EPA EJScreen"], "sourcesMissing": ["FEMA NRI", "EPA AirNow", "311 Service Requests"] } } ``` A coastal cell in a repeat-loss corridor will typically score high on `Flood Risk` (because it sits in a regulatory `AE` or `V` zone) *and* low on `Flood Loss History` (because NFIP has paid out repeated claims there). Use both sub-scores together when ranking cells for hazard-sensitive use cases — relying on the FIRM zone alone will under-flag the worst pluvial-flood corridors. ### Complaint Trend YoY (AXL-107) [#complaint-trend-yoy-axl-107] `Complaint Trend YoY` is a directional companion to the volume-based `Complaint Density` and `Complaint Velocity` sub-scores. Density measures how loud a cell is *right now*; velocity measures the 30-day change; the YoY delta measures whether that loudness is rising or falling against the same window one year ago — the slow-moving signal that volume and short-window velocity both miss. The sub-score is computed in-app from the same `service_requests_311` rows the scorer already pulls for density and resolution time, so no additional data source is required: 1. Count 311 complaints in the trailing 30 days (`density_30d`). 2. Count 311 complaints in the matching 30-day window one year prior (the 335-to-395-day window). 3. Compute the YoY delta as `(current − prior) / max(prior, 1)`, capped at `+5×` to bound runaway ratios in cells with a near-zero prior baseline. 4. Map the delta onto a 0–100 safety contribution: `−1` (complaints down 100%) → 100, `+3` (complaints up 3×) → 0, with values above `+3×` saturating at 0. Negative YoY (complaints trending down) lifts the cell's safety score; positive YoY (complaints rising) penalizes it. Rising 311 density is treated as a Pioneer Stage 1 signal — the same complaint-acceleration pattern that typically precedes pioneer-business clustering by 12–24 months and feeds the [Pioneer Signal](#pioneer-signal-and-early-stage-gentrification-indicator) cascade. When both the current and prior 30-day windows are empty for a cell, the sub-score is omitted from `subScores` and `AXL-107 (311 YoY)` appears in `sourcesMissing` for the group rather than emitting a misleading "improving" signal from a quiet cell with no complaint history. Cells in metros without 311 ingestion will always show this source as missing. ```json { "safetyEnvironment": { "score": 67.1, "subScores": [ { "name": "Crime Rate", "score": 72, "weight": 0.30, "source": "Local Police" }, { "name": "Complaint Density", "score": 64, "weight": 0.05, "source": "311 Service Requests" }, { "name": "Complaint Velocity", "score": 58, "weight": 0.05, "source": "311 Service Requests Velocity" }, { "name": "Complaint Trend YoY", "score": 81, "weight": 0.05, "source": "AXL-107 (311 YoY)" } ], "sourcesUsed": ["Local Police", "311 Service Requests", "311 Service Requests Velocity", "AXL-107 (311 YoY)"] } } ``` Read all four 311 sub-scores together when interpreting a cell: a cell with high `Complaint Density` *and* a high (improving) `Complaint Trend YoY` is loud-but-getting-quieter, while a cell with low density *and* a low (deteriorating) trend score is quiet-but-getting-louder — the kind of leading indicator that volume alone obscures. ### Utility Complaint Density (ICC) [#utility-complaint-density-icc] `Utility Complaint Density` captures unresolved utility-service friction — outages, billing disputes, service-quality complaints — that shows up as formal filings with a state utility commission. It's a leading indicator for infrastructure stress that neither crime data nor FEMA flood maps pick up. The sub-score is computed from the ICC (Illinois Commerce Commission) utility-complaint feed, joined to the cell via the same zip-level nearest-neighbor lookup that powers `Flood Loss History`: 1. Find the nearest US zip centroid to the cell. 2. Count ICC utility complaints at that zip in the trailing FY window. 3. Log-scale the count against the observed distribution (median 4, p90 22, p99 91 complaints/zip) and invert to a 0–100 safety contribution: 0 complaints → 100, saturating toward 0 above \~150. The dataset is **\~91% Illinois** — this is a single-state FOIA extract, not a national commission-complaint aggregate. Cells outside Illinois will almost always show `ICC` in `sourcesMissing` rather than a misleading zero-complaint "clean" record. Treat this sub-score as an Illinois-only enrichment for now; do not infer utility health for non-IL cells from its absence. ```json { "safetyEnvironment": { "score": 61.8, "subScores": [ { "name": "Crime Rate", "score": 72, "weight": 0.20, "source": "Local Police" }, { "name": "Utility Complaint Density", "score": 34, "weight": 0.04, "source": "ICC" } ], "sourcesUsed": ["Local Police", "ICC"] } } ``` ### Nuclear Facility Proximity (NRC) [#nuclear-facility-proximity-nrc] `Nuclear Facility Proximity` is a proximity penalty for cells that fall inside the NRC's emergency-planning zones (EPZs) around operating and decommissioning reactor sites. It rides alongside `Environmental Risk` and `Natural Hazard Risk` as a discrete, regulatory-anchored hazard layer that the EJScreen and NRI composites do not surface directly. The sub-score is computed by: 1. Scanning NRC-licensed reactor sites (operating + decommissioning units, \~68 site locations) for the nearest site to the cell centroid using a haversine distance. 2. Mapping distance onto a linear decay between the NRC's two published EPZ radii: * **16 km (\~10 mi)** — the plume-exposure EPZ. Cells at or inside this radius score `0` (minimum safety contribution from this signal). * **80 km (\~50 mi)** — the ingestion-pathway planning zone. Cells at or beyond this radius score `100` (no meaningful nuclear-proximity penalty). 3. Linearly interpolating between the two anchors for cells in the 16–80 km band. The 16/80 km anchors are the NRC's own EPZ radii, not tuned parameters. The site coordinates are backfilled at city/township precision via a plant-name → site-coordinate crosswalk (68 sites) — adequate for the EPZ-scale proximity signal, not for anything finer. ```json { "safetyEnvironment": { "score": 58.9, "subScores": [ { "name": "Crime Rate", "score": 72, "weight": 0.20, "source": "Local Police" }, { "name": "Nuclear Facility Proximity", "score": 42, "weight": 0.05, "source": "NRC" } ], "sourcesUsed": ["Local Police", "NRC"] } } ``` Cells far from any US reactor site score at or near 100 on this sub-score — it never *rewards* proximity, only penalizes it. Use it together with `Environmental Risk` and `Natural Hazard Risk` when ranking cells for hazard-sensitive use cases (data centers, hospitals, long-hold industrial siting). ## Economic strength sub-scores [#economic-strength-sub-scores] The `economicStrength` group rolls up employment, wage, GDP, banking, small-business lending, innovation, and federal-tenancy signals. | Sub-score | Weight | Source | What it measures | | ---------------------- | ------ | -------- | ----------------------------------------------------------------------------- | | Employment Growth | 0.24 | BLS QCEW | Trailing employment change in the cell's county. | | Avg Wages | 0.20 | BLS QCEW | Average weekly wage in the cell's county. | | GDP Growth | 0.16 | BEA | Metro-level real GDP change. | | Banking Activity | 0.13 | FDIC | Deposits per capita in the cell's zip. | | Innovation Density | 0.12 | USPTO | Patent count for the cell's metro. | | Small Biz Lending | 0.08 | SBA | 7(a) + 504 loan volume in the cell's county. | | Federal Lease Presence | 0.07 | GSA FRPP | Federal-agency leased square footage in the cell's H3 query ring — see below. | ### Federal Lease Presence (GSA FRPP) [#federal-lease-presence-gsa-frpp] `Federal Lease Presence` treats federal-agency tenancy as a **positive** economic anchor. Federal leases are long-dated, credit-strong, and slow to move — a dense cluster of federal RSF (rentable square footage) around a cell is a durable institutional signal that CRE fundamentals in the area are underwritten by government tenancy, not just private demand. The sub-score is computed from the GSA Federal Real Property Profile (FRPP) FOIA extract: 1. Sum leased RSF across every federal lease that falls inside the cell's H3 query ring (not just the exact cell — federal tenancy spills over into the immediate neighborhood). 2. Log-scale the summed RSF between **2,000 sqft** (a very small satellite office) and **750,000 sqft** (a dense multi-agency federal cluster). 3. Map onto 0–100: a single median-sized federal office lease (\~8,700 sqft) contributes \~25/100; a large multi-lease cluster saturates to 100. Cells with no federal leases anywhere in the query ring omit the sub-score and list `GSA FRPP` in `sourcesMissing`. This is the most common state — federal-lease footprints are geographically concentrated (metro cores, agency campuses, courthouses, ports of entry), so a missing sub-score is a genuine "no federal anchor here" reading, not a data-quality gap. ```json { "economicStrength": { "score": 74.1, "subScores": [ { "name": "Employment Growth", "score": 68, "weight": 0.24, "source": "BLS QCEW" }, { "name": "Avg Wages", "score": 72, "weight": 0.20, "source": "BLS QCEW" }, { "name": "Federal Lease Presence", "score": 88, "weight": 0.07, "source": "GSA FRPP" } ], "sourcesUsed": ["BLS QCEW", "GSA FRPP"] } } ``` Federal leases also project into the Codex as `codex_entities` (entity\_type = `facility`) — see the Codex documentation if you need the underlying per-lease records rather than the aggregated score contribution. ## Business vitality sub-scores [#business-vitality-sub-scores] The `businessVitality` group rolls up business openings/closings, category diversity, rating momentum, review activity, establishment density, health inspections, license velocity, pioneer businesses, and regulatory friction. | Sub-score | Weight | Source | What it measures | | --------------------------------------- | ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Growth Rate | 0.21 | Google Places | Net business openings vs. closings normalized against total establishments. | | Yelp Activity | 0.14 | Yelp | Composite of average rating, review velocity, and new-listing count. | | License Velocity | 0.12 | Business Licenses | New-license issuance rate in the cell's window. | | Category Diversity | 0.11 | Google Places | Distinct business categories represented in the cell. | | Rating Trajectory | 0.11 | Google Places | Direction of average rating change over the window. | | Establishment Density | 0.09 | Census CBP | Establishments per cell from County Business Patterns. | | Pioneer Business Presence | 0.08 | AXL-7 | Pioneer-business count feeding the [Pioneer Signal](#pioneer-signal-and-early-stage-gentrification-indicator) cascade. | | Commercial Health | 0.05 | Health Inspections | Average health-inspection score in the cell. | | Nightlife Pipeline | 0.05 | Liquor Licenses | New liquor-license issuance rate. | | Broker Discipline (Regulatory Friction) | 0.04 | NY DOS | State-level real-estate broker disciplinary consent orders — see below. | ### Broker Discipline (NY DOS) [#broker-discipline-ny-dos] `Broker Discipline` is a **regulatory-friction penalty** on business vitality — a rising volume of formal disciplinary actions against real-estate brokers in a state signals that the transaction environment is contentious, and that some share of local CRE activity is being litigated rather than transacted cleanly. The sub-score is computed from the NY Department of State (DOS) real-estate broker disciplinary consent-order FOIA extract: 1. Count distinct DOS disciplinary case files (`dos_file_number`) for the cell's **state**. 2. Log-scale the count between 1 and 100 disciplinary actions, then invert to a 0–100 contribution: fewer actions → higher score, more actions → lower score. **This is a state-level join, not a per-cell signal.** The underlying FOIA snapshot has no per-record address, coordinates, or licensee zip — the field simply is not in the source. That means every cell in the same state shares the same disciplinary count, and by extension the same sub-score contribution. The weight is intentionally low (0.04) to reflect this: a flat state-wide value should never swing an individual cell's business-vitality score materially. The current extract is a single fiscal-year, single-state (NY) sample — 62 rows across 40 distinct case files. Cells outside NY show `NY DOS` in `sourcesMissing` and pay no penalty. Do not read a missing `NY DOS` sub-score on a non-NY cell as "clean regulatory environment"; read it as "no state-level broker-discipline data available for this state." ```json { "businessVitality": { "score": 66.4, "subScores": [ { "name": "Growth Rate", "score": 71, "weight": 0.21, "source": "Google Places" }, { "name": "License Velocity", "score": 68, "weight": 0.12, "source": "Business Licenses" }, { "name": "Broker Discipline (Regulatory Friction)", "score": 42, "weight": 0.04, "source": "NY DOS" } ], "sourcesUsed": ["Google Places", "Business Licenses", "NY DOS"] } } ``` Broker-discipline case files also project into the Codex as `codex_events` (event\_type = `broker_disciplinary_action`) — use the Codex directly if you need per-case detail rather than the aggregated state-level score contribution. ## Confidence semantics [#confidence-semantics] Every Locus response includes a `confidence` field (0.0–1.0) representing the ratio of expected data sources that returned data for the location. ```json { "composite": 78.4, "confidence": 0.92, "sourcesUsed": 36, "sourcesTotal": 43 } ``` * **0.9+ (high)** — almost all data sources contributed; treat as authoritative. * **0.7–0.9 (medium)** — significant signals present; treat as directional, not exact. * **0.5–0.7 (low)** — sparse coverage; useful for filtering but not for ranking. * **\<0.5 (very low)** — Locus returns the score for transparency but it should not be used for production decisions. Confidence varies by metro. Major US metros (top 50 MSAs) consistently exceed 0.85. Rural areas, US territories, and international markets often fall below 0.7. ## Coverage guards on signal groups [#coverage-guards-on-signal-groups] Some signal groups include a **minimum-source guard** to prevent a single universally-available data source from dominating the group score for cells where every other source is missing. When a group's coverage guard isn't met, the group emits a neutral **no-signal score of 50** and a `confidence` of `0`, with an empty `subScores` array — instead of returning a misleadingly high or low score derived from one input. | Signal group | Minimum sub-signals | Reason | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `safetyEnvironment` | 2 | FEMA flood zone is available for almost every US cell (typically `X` = 100). Without a guard, cells with no crime, EJScreen, NRI, AQI, NFIP loss history, or 311 data would score 100/100 on safety purely because of flood-zone coverage. | | All other groups | 1 (no guard) | These groups don't currently have a high-scoring, universally-available source that would dominate the average. | Example response for a rural cell where only FEMA flood zone is available: ```json { "safetyEnvironment": { "score": 50, "confidence": 0, "subScores": [], "sourcesUsed": [], "sourcesMissing": ["Local Police", "AXL-109 (FEMA NFIP)", "EPA EJScreen", "FEMA NRI", "EPA AirNow", "311 Service Requests"] } } ``` Treat a `safetyEnvironment.score` of `50` paired with `confidence: 0` as **"no safety signal available"** — not as "neutral safety." The 50 is a placeholder so the composite score can still be computed; it is not a measurement. Use the `confidence` field to filter these cells out of safety-sensitive ranking lists. ## Pioneer Signal and early-stage gentrification indicator [#pioneer-signal-and-early-stage-gentrification-indicator] Locus includes a **Pioneer Signal** detection system that identifies early signs of neighborhood transformation. The system tracks a multi-stage cascade that typically precedes gentrification by 12–24 months: 1. **Pioneer businesses** — new specialty coffee shops, art galleries, or co-working spaces appear in a previously underserved area. 2. **Council language shift** — city council meeting minutes begin referencing "revitalization," "mixed-use," or "transit-oriented development" for the area. 3. **Permit acceleration** — building permit velocity increases, particularly renovation and change-of-use permits. 4. **Rezoning activity** — formal rezoning applications or variance requests are filed. These stages feed into the **Early-Stage Gentrification Indicator (ESGI)**, a score returned alongside the composite score in scoring responses. The ESGI combines causal edge attribution, upzoning probability, litigation risk, and spatial spillover effects to quantify how likely a cell is to experience rapid value change. ```json { "composite": 78.4, "esgi": { "score": 0.72, "stage": "permit_acceleration", "upzoning_probability": 0.45, "litigation_risk": 0.12, "spatial_spillover": 0.31 } } ``` | Field | Type | Description | | --------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- | | `esgi.score` | float | ESGI score from 0.0 to 1.0 indicating transformation likelihood. | | `esgi.stage` | string | Current cascade stage: `pioneer_businesses`, `council_language_shift`, `permit_acceleration`, or `rezoning_activity`. | | `esgi.upzoning_probability` | float | Probability that the cell will be upzoned within 12 months. | | `esgi.litigation_risk` | float | Risk of development delays from litigation or community opposition. | | `esgi.spatial_spillover` | float | Influence from transformation activity in neighboring cells. | ## Uncertainty quantification [#uncertainty-quantification] Scoring responses include uncertainty metadata that helps you assess how much to trust a given score. Locus runs a Monte Carlo simulation (96 samples) with confidence-aware noise injection to produce: * **Confidence intervals** — geo-conformal prediction intervals at 80% and 90% coverage. * **Sobol sensitivity indices** — first-order and total-order indices showing which signal groups contribute most to score variance. * **Epistemic flags** — signals where data is sparse or conflicting, flagged for transparency. * **Spatial Sharpe ratio** — a risk-adjusted score metric analogous to a financial Sharpe ratio, indicating score stability relative to spatial neighbors. Request uncertainty data by adding `include=uncertainty` to any scoring endpoint: ```bash curl "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194&include=uncertainty" ``` ```json { "composite": 78.4, "confidence": 0.92, "uncertainty": { "ci_80": [72.1, 84.7], "ci_90": [69.5, 87.3], "spatial_sharpe": 1.42, "sobol_first_order": { "businessVitality": 0.28, "developmentPipeline": 0.22, "demographics": 0.15, "accessibility": 0.12, "economicStrength": 0.10, "safetyEnvironment": 0.07, "populationMomentum": 0.04, "amenityDemand": 0.02 }, "epistemic_flags": ["populationMomentum"] } } ``` | Field | Type | Description | | ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | | `uncertainty.ci_80` | array | 80% confidence interval \[lower, upper] for the composite score. | | `uncertainty.ci_90` | array | 90% confidence interval \[lower, upper]. | | `uncertainty.spatial_sharpe` | float | Risk-adjusted score relative to neighboring cells. Values above 1.0 indicate the score is stable compared to peers. | | `uncertainty.sobol_first_order` | object | First-order Sobol indices per signal group. Higher values mean that group drives more score variance. | | `uncertainty.epistemic_flags` | array | Signal groups with sparse or conflicting data. | ## Per-cell consensus class [#per-cell-consensus-class] The `uncertainty` payload tells you how noisy a score is given the data feeding it. The **consensus class** answers a different question: *would this score still hold if Locus had aggregated to a different grid?* It is a per-cell sensitivity check against the [Modifiable Areal Unit Problem (MAUP)](https://en.wikipedia.org/wiki/Modifiable_areal_unit_problem) — the well-known finding that spatial statistics can move materially when the underlying grid changes. Locus computes a `consensus_class` for every cell by comparing the cell's percentile rank within its metro at the default resolution against the percentile rank of the parent (coarser) hex it sits inside. When the two ranks agree the score is robust to grid choice; when they diverge the score is at least partly a grid artifact. The classification is surfaced on `/api/cells/detail` (the endpoint that powers the Explorer's cell-detail panel) as three fields: | Field | Type | Description | | ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `consensus_class` | string \| null | One of `stable_core`, `ambiguity_shell`, `stable_non_signal`, or `null` if the cell has not yet been classified. | | `support_stability` | float \| null | Agreement between the cell's resolution-8 percentile and its resolution-7 parent percentile within the metro. `1.0` = perfect agreement, `0.0` = the two supports disagree completely. | | `consensus_computed_at` | string \| null | ISO-8601 timestamp of the most recent classification run for this cell. | ### Class definitions [#class-definitions] | Class | When it fires | How to read it | | ------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `stable_core` | `support_stability ≥ 0.80` and the cell sits above the bottom quartile of its metro. | The score is robust to grid choice. Treat as a high-confidence ranking. | | `ambiguity_shell` | `0.20 ≤ support_stability < 0.80`. | The cell ranks materially differently when re-aggregated to a coarser grid. Use the score directionally and pair it with neighbors before acting. | | `stable_non_signal` | The cell is consistently in the bottom quartile of its metro across both supports. | Genuinely quiet. The low score is not a grid artifact — it is the same answer at every resolution. | A cell shows `consensus_class: null` until the classification job has populated its row. Treat `null` the same way you'd treat `confidence: null` — render no robustness badge rather than guessing. ### Example response [#example-response] ```json { "h3_index": "882a100d63fffff", "composite_score": 78.4, "support_stability": 0.92, "consensus_class": "stable_core", "consensus_computed_at": "2026-04-29T20:14:00Z" } ``` ### When to use it [#when-to-use-it] * **Ranking and shortlisting.** Filter to `consensus_class = stable_core` when you need the most defensible top-N list — those cells survive a grid change. * **Risk-flagging the long tail.** Cells in `ambiguity_shell` are the cells most worth a human review before commitment. They typically sit on tier boundaries where small grid choices flip rankings. * **Suppressing false-positive low scores.** A `stable_non_signal` cell is genuinely low across grids — a `stable_non_signal` paired with a `composite_score` of 35 means the cell is reliably quiet, not under-sampled. The classification is recomputed after every material scoring-engine change. The companion [Spatial Sharpe ratio](#uncertainty-quantification) gives you the same robustness intuition relative to *neighbors* rather than relative to *grid resolution* — combine both when filtering for production-grade rankings. ## Data freshness [#data-freshness] | Source | Refresh cadence | Lag | | --------------------------------- | ----------------------- | ------------------------------- | | POI inventory (Google Places) | Weekly | \<7 days | | Building permits (city open data) | Per-city; mostly weekly | 7-30 days depending on city | | Traffic patterns (state DOTs) | Monthly | 30-60 days | | Transit ridership (FTA NTD) | Monthly | 60-90 days (FTA publishing lag) | | USPS vacancy (HUD) | Quarterly | 90-120 days | | Jobs (BLS QCEW) | Quarterly | 90 days (BLS publishing lag) | | Demographics (Census ACS) | Annual | 12-18 months | | Real estate listings | Daily (where available) | 1-3 days | | Crime (UCR/local) | Monthly | 30-60 days | The `freshness` metadata in score responses tells you the oldest source feeding a given response — useful for deciding whether to cache. ## API stability commitments [#api-stability-commitments] * **Cell IDs** — frozen across major API versions * **Scoring profile names** — frozen * **Composite + sub-score scales (0–100)** — frozen * **Confidence semantics** — frozen * **Sub-score names within a group** — may change with 90-day notice * **Underlying data sources** — may change without notice (we pick the best available) * **Weight tuning per profile** — adjusted quarterly based on backtesting; minor adjustments not announced, major rebalances get a 30-day blog post If a profile's behavior changes meaningfully, you'll see a `profile_version` bump in the response. Pin to a specific `profile_version` if you need replicable scores across time. ## What Locus doesn't include [#what-locus-doesnt-include] Locus is **non-PII**. We do not include: * Individual person data (names, addresses, phone numbers) * Mobile-device location traces (Locus uses aggregated patterns, not raw movements) * Customer-specific data unless you explicitly upload it via `/api/data/upload` Aggregations resolving to fewer than 25 people (or 5 households for residential metrics) are suppressed in responses with a `suppressed: true` flag. # ZBA decisions (/locus/zba-decisions) The **ZBA Decisions** dashboard is a cross-jurisdiction search surface over Locus's normalized Zoning Board of Appeals catalog. Use it to find variance and special-permit outcomes by jurisdiction, case number, address, decision date, or outcome — and to pull a filtered set as CSV for entitlement, due-diligence, or land-use research. The page lives at [`/zba-decisions`](https://app.axiomlocus.io/zba-decisions) inside the Locus app and is backed by [`GET /api/zba-decisions/search`](#api). ## Coverage [#coverage] The catalog covers four ZBA jurisdictions, ingested from a mix of structured open-data portals and PDF-based agendas. | Jurisdiction slug | Source | Ingestion type | | ----------------- | ---------------------------- | ---------------- | | `nyc` | NYC Open Data (Socrata) | Structured API | | `philly` | OpenDataPhilly (Carto) | Structured API | | `chicago` | Curated jurisdictional feeds | Structured + PDF | | `boston` | Curated jurisdictional feeds | Structured + PDF | NYC and Philadelphia run on dedicated upstream API collectors so refresh cadence matches the underlying portals — typically daily for NYC Socrata and several times per week for Philly Carto. Chicago and Boston are sourced from a mix of structured feeds and PDF-decision parsers, so cadence varies by hearing schedule. ## When to use it [#when-to-use-it] Reach for this dashboard when you need to: * Triage entitlement risk for a target site by reviewing recent variances on adjacent parcels. * Track outcome rates (Approved / Denied / Granted with Conditions) for a specific variance type or jurisdiction. * Pull a date-bounded set of decisions into a CSV for diligence binders or model training. * Click through to the original decision document on the source jurisdiction's portal. ## Filters [#filters] Every filter narrows the result set on the server side and resets pagination to the first page. | Filter | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Jurisdiction** | One or more of `chicago`, `boston`, `nyc`, `philly`. Multi-select. | | **Case # or address** | Substring match (`ILIKE`) against either `case_number` **or** `address` — use the same input to search by either. | | **Outcome** | Exact match — one of `Approved`, `Denied`, `Granted`, `Granted with Conditions`, `Pending`, `Withdrawn`. | | **Variance type** | Substring match against `variance_type` (for example, `use`, `bulk`, `setback`, `parking`). | | **Date from / Date to** | Inclusive bounds on `decision_date`. Either bound is optional. | A **Reset filters** link clears every active filter; it appears only when at least one is set. ## Sorting and pagination [#sorting-and-pagination] | Column | Default | Notes | | -------------------------------------- | ---------- | ----------------------------------------------- | | **Decision Date** (`decision_date`) | Descending | The default sort — most recent decisions first. | | **Occurred At** (`occurred_at`) | — | Upstream event timestamp. | | **Jurisdiction** (`jurisdiction_slug`) | — | Alphabetical. | Click any column header to sort by it; click again to flip direction. Results paginate at **50 per page**. ## Result columns [#result-columns] Each row corresponds to one ZBA decision: * **Case #** — the upstream case or docket number. * **Jurisdiction** — normalized jurisdiction slug. * **Address** — subject-property address as reported. * **Variance type** — truncated to 40 characters in the table; full text available via the API. * **Outcome** — color-coded badge (green for `Approved` / `Granted`, red for `Denied`, amber for `Granted with Conditions`, blue for `Pending`). * **Decision Date** — locale-formatted. * **External-link icon** — opens the decision's `source_url` (the original portal record or PDF) in a new tab. Shown only when a source URL is present. ## Export [#export] Click **Export CSV** to download the **currently visible page** as `zba-decisions.csv`. The export honors active filters and sort, and includes: `Case Number, Jurisdiction, Address, Variance Type, Outcome, Decision Date, Conditions` (conditions truncated to 200 characters). ## API [#api] ### `GET /api/zba-decisions/search` [#get-apizba-decisionssearch] Returns a page of normalized ZBA decisions, plus the total count for the active filter set. **Query parameters** | Parameter | Type | Description | | --------------- | -------- | --------------------------------------------------------------------- | | `jurisdictions` | `string` | Comma-separated jurisdiction slugs (e.g. `nyc,philly`). | | `case_q` | `string` | Substring matched against either `case_number` or `address`. | | `outcome` | `string` | Exact match — see allowed values above. | | `variance_type` | `string` | Substring match against `variance_type`. | | `date_from` | `string` | Inclusive lower bound on `decision_date` (`YYYY-MM-DD`). | | `date_to` | `string` | Inclusive upper bound on `decision_date` (`YYYY-MM-DD`). | | `sort_by` | `string` | One of `decision_date` (default), `occurred_at`, `jurisdiction_slug`. | | `sort_dir` | `string` | `asc` or `desc` (default). | | `limit` | `number` | Page size. Default `50`, capped at `200`. | | `offset` | `number` | Zero-based offset. Default `0`. | **Response shape** ```json { "decisions": [ { "source_key": "nyc:2024-0123", "jurisdiction_slug": "nyc", "source": "nyc-socrata", "source_url": "https://data.cityofnewyork.us/...", "case_number": "2024-0123-BZ", "decision_date": "2026-04-12", "variance_type": "Use variance — eating and drinking establishment", "outcome": "Granted with Conditions", "conditions_text": "Subject to operating hours of 7 AM–11 PM…", "address": "123 W 14TH ST", "decision_text": "The Board grants the application…", "occurred_at": "2026-04-12T00:00:00Z", "ingested_at": "2026-04-13T05:00:00Z" } ], "total": 312, "limit": 50, "offset": 0 } ``` **Example** ```bash Recent denials in NYC and Philadelphia curl 'https://app.axiomlocus.io/api/zba-decisions/search?jurisdictions=nyc,philly&outcome=Denied&date_from=2026-01-01&limit=100' \ -H 'Cookie: ' ``` The endpoint requires an authenticated Locus session; unauthenticated calls return `401 Unauthorized`. ## Related [#related] Search normalized business licenses across U.S. metros. Cell-level scoring that incorporates zoning and entitlement signals. # AIS coverage (/overwatch/ais-coverage) Overwatch receives live AIS position reports through [AISStream](https://aisstream.io) and stores them so that maps, investigations, and cargo estimates always reflect current vessel activity. By default, Overwatch subscribes to AIS data around each monitored port. Two environment variables let you control how much ocean area is covered. ## Coverage modes [#coverage-modes] ### Port-based coverage (default) [#port-based-coverage-default] Overwatch computes a bounding box around each port zone polygon and subscribes to AIS messages within that area. The `AISSTREAM_BBOX_BUFFER_DEG` variable controls how far the bounding box extends beyond the port boundary. | Value | Approximate radius | Typical vessel count | | --------------- | ------------------ | -------------------- | | `0.5` | \~55 km | \~1–2 K | | `2.0` (default) | \~220 km | \~3–5 K | | `5.0` | \~550 km | \~10–20 K | A larger buffer catches vessels that are in transit approaching or departing a port, so map views populate before a vessel reaches anchorage. ```bash # Increase the buffer to ~550 km around each port AISSTREAM_BBOX_BUFFER_DEG=5.0 ``` ### Global coverage [#global-coverage] Set `AISSTREAM_GLOBAL=1` to subscribe to a single planet-wide bounding box (`-90/-180` to `90/180`). This replaces all port-derived bounding boxes and delivers positions for every vessel broadcasting AIS worldwide (\~175,000 distinct vessels). ```bash # Enable global AIS coverage AISSTREAM_GLOBAL=1 ``` Global coverage delivers **100,000–300,000 vessel positions** at any given time compared to approximately 3,000–5,000 with port-based coverage. Make sure your database and infrastructure can handle the increased write volume before enabling this option. ## In-zone vs. background positions [#in-zone-vs-background-positions] When `AISSTREAM_GLOBAL=1` is on, Overwatch splits each incoming position by whether the vessel is inside a monitored port or chokepoint bounding box: * **In-zone positions** (inside any monitored box) behave exactly like port-based coverage. They are written to `ais_positions` history, feed the intelligence pipeline (port events, dark-event detection, course-anomaly scoring, cargo estimation, EWMAs), and update `vessel_states`. * **Background positions** (outside every monitored box) are map-only. They flow through a latest-wins, per-vessel-throttled buffer directly into `vessel_states` — no `ais_positions` history row, no analytics side effects. The live map's worldwide layer reads from `vessel_states` and `vessels_live_tiles`, so background vessels still appear on the map with a fresh last-known position. `lastSeen` is still updated on every background frame so that when a vessel later enters a monitored zone after a long ocean transit, the entry is not misread as a dark-event gap. In-zone behavior is byte-for-byte identical to port-based coverage. The changes below only affect vessels outside the monitored boxes. ## Environment variables [#environment-variables] ### Coverage [#coverage] | Variable | Default | Description | | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `AISSTREAM_BBOX_BUFFER_DEG` | `2.0` | Buffer in degrees added around each port zone polygon when computing bounding boxes. Ignored when `AISSTREAM_GLOBAL=1`. | | `AISSTREAM_GLOBAL` | `0` | Set to `1` to subscribe to a single worldwide bounding box, bypassing port-derived boxes entirely. | ### Background ingestion (`AISSTREAM_GLOBAL=1` only) [#background-ingestion-aisstream_global1-only] These knobs tune how out-of-zone positions are coalesced and written. Defaults are chosen for a \~175 K-vessel global feed; leave them alone unless you are seeing DB pressure or map-freshness issues. | Variable | Default | Description | | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GLOBAL_BACKGROUND_MIN_INTERVAL_S` | `600` | Minimum seconds between accepted background writes for the same vessel. Lower values freshen the map faster at the cost of more `vessel_states` upserts. | | `GLOBAL_BACKGROUND_FLUSH_MS` | `30000` | How often (ms) the background buffer drains its pending rows to the database. | | `GLOBAL_BACKGROUND_UPSERT_CHUNK` | `500` | Maximum rows per background upsert batch. Lower this if you hit statement-size limits. | | `STATIC_DATA_DB_MIN_INTERVAL_S` | `21600` | Minimum seconds between database writes of Type 5 static data (name, IMO, dimensions) for the same vessel. The in-memory MMSI→IMO cache is still updated on every frame. | | `MMSI_RECOVERY_RETRY_S` | `1800` | Minimum seconds between database lookups when trying to recover an IMO for an unknown MMSI. Prevents one query per position for vessels that will never be resolved. | | `AIS_MAX_STUBBED_IMOS` | `300000` | Maximum entries in the in-memory stub-vessel cache. Sized above the global fleet (\~175 K) so the cache is not repeatedly cleared under global-mode load. | Example: freshen the worldwide map every 5 minutes and drain every 15 seconds. ```bash AISSTREAM_GLOBAL=1 GLOBAL_BACKGROUND_MIN_INTERVAL_S=300 GLOBAL_BACKGROUND_FLUSH_MS=15000 ``` ## When to adjust coverage [#when-to-adjust-coverage] * **Maps look empty far from port** — increase `AISSTREAM_BBOX_BUFFER_DEG` to catch in-transit vessels earlier. * **You want worldwide last-known coverage on the live map** — enable `AISSTREAM_GLOBAL=1`. Background positions keep the map fresh without writing full position history for the whole planet. * **Background writes are still too heavy** — raise `GLOBAL_BACKGROUND_MIN_INTERVAL_S` (fewer accepted samples per vessel) or `STATIC_DATA_DB_MIN_INTERVAL_S` (fewer static-data upserts). * **Storage or compute costs are too high** — reduce `AISSTREAM_BBOX_BUFFER_DEG` to limit data volume, or leave global mode off. Position data is automatically downsampled and archived over time to manage storage. See [data retention and downsampling](/overwatch/data-retention) for details on retention windows and resolution tiers. # Analytical Parquet snapshots (/overwatch/analytical-snapshots) Overwatch publishes a nightly Parquet snapshot of a small allowlist of analytical tables to a DigitalOcean Spaces bucket. The live Postgres database (Supabase) remains the source of truth for application reads — these snapshots exist so batch workloads can scan flat columnar files in DuckDB instead of hammering the OLTP database. Use the snapshots when you are running: * A DuckDB or `dbt-duckdb` model that aggregates across many days of history. * An entity-resolution batch (for example Splink) that needs a stable, immutable input. * Ad-hoc analytical queries from a notebook that should not contend with production traffic. For real-time reads — vessel positions, port congestion, alerts — keep using the Overwatch API and the live database. ## How it works [#how-it-works] A nightly job runs DuckDB with the `postgres_scanner`, `spatial`, and `httpfs` extensions loaded. For each table in the allowlist it executes a `COPY (SELECT * FROM pg.) TO 's3://…/

.parquet' (FORMAT PARQUET, COMPRESSION ZSTD)` against Postgres and streams the result straight into object storage. No intermediate disk staging. Each run also writes a tiny CSV manifest at `s3:///latest/

.path` whose single `snapshot_date` column points consumers at the most recent dated partition. S3-compatible stores don't support symlinks, so the manifest serves the same purpose. ## Snapshotted tables [#snapshotted-tables] The allowlist is intentionally narrow. Raw `ais_positions` is **never** snapshotted — it is the high-volume telemetry table and its inclusion would dominate storage and I/O. For position history, query the live database (see [data retention](/overwatch/data-retention)) or request a rehydration from the archive. | Table | What it holds | | -------------------------- | --------------------------------------------------- | | `metros` | Metropolitan area reference data. | | `h3_cells` | H3 hex cell grid used by Locus and the cell scorer. | | `pois` | Points of interest registry. | | `poi_snapshots` | Per-POI observation history. | | `collection_runs` | Collector run metadata. | | `monitored_locations` | User-configured monitored locations. | | `alert_history` | Historical alert events. | | `cell_scores` | Latest per-cell scoring outputs (\~50 MB/day). | | `cell_score_history` | Time series of cell scores. | | `locus_validation_metrics` | Locus model validation outputs. | | `locus_scoring_formulas` | Configured Locus scoring formulas. | | `locus_export_schedules` | Locus export schedule definitions. | ## Output layout [#output-layout] ```text s3://axiom-parquet-snapshots/snapshots//

.parquet s3://axiom-parquet-snapshots/latest/

.path ``` Files are Zstandard-compressed Parquet. The `snapshots//` partitions are immutable; the `latest/` manifests are overwritten on each run. ## Reading a snapshot from DuckDB [#reading-a-snapshot-from-duckdb] Point DuckDB's `httpfs` extension at the bucket and scan the Parquet file directly: ```sql INSTALL httpfs; LOAD httpfs; CREATE SECRET axiom_spaces ( TYPE s3, KEY_ID '...', SECRET '...', REGION 'nyc3', ENDPOINT 'nyc3.digitaloceanspaces.com', URL_STYLE 'path', USE_SSL true ); -- Resolve the latest dated partition from the manifest, then scan it. WITH latest AS ( SELECT snapshot_date FROM read_csv_auto('s3://axiom-parquet-snapshots/latest/cell_scores.path') ) SELECT * FROM read_parquet( 's3://axiom-parquet-snapshots/snapshots/' || (SELECT snapshot_date FROM latest) || '/cell_scores.parquet' ) LIMIT 100; ``` For pinned reproducibility — for example a dbt run or an ER batch — read a specific dated partition directly instead of going through `latest/`. ## Storage and retention [#storage-and-retention] `cell_scores` is the largest table at roughly 50 MB per day; the other tables are smaller. The bucket is configured with a 90-day lifecycle policy, so dated partitions older than 90 days are deleted automatically. If you need older history, copy the partition you need into a long-term archive before it expires. Snapshots are an analytical convenience, not a backup. The live Postgres database and the AIS archive remain the systems of record. See [data retention](/overwatch/data-retention) for how raw operational data is preserved. ## Configuration [#configuration] The job is parameterized through environment variables. Postgres and Spaces credentials are required; everything else has a sensible default. | Variable | Default | Description | | ----------------- | ----------------------------- | -------------------------------------------------- | | `PG_HOST` | — | Supabase Postgres host. **Required.** | | `PG_PASS` | — | Postgres password. **Required.** | | `SPACES_KEY` | — | DigitalOcean Spaces access key. **Required.** | | `SPACES_SECRET` | — | DigitalOcean Spaces secret key. **Required.** | | `PG_PORT` | `5432` | Postgres port. | | `PG_USER` | `postgres` | Postgres user. | | `PG_DATABASE` | `postgres` | Postgres database name. | | `SPACES_REGION` | `nyc3` | Spaces region. | | `SPACES_ENDPOINT` | `nyc3.digitaloceanspaces.com` | Spaces S3 endpoint. | | `SPACES_BUCKET` | `axiom-parquet-snapshots` | Target bucket name. | # Data retention and downsampling (/overwatch/data-retention) Overwatch continuously ingests AIS vessel positions at full resolution — often multiple reports per vessel per second. To keep the live database performant without losing historical data, Overwatch applies a three-stage lifecycle: hot retention in the live database, tiered downsampling to reduce density over time, and long-term archival to cold storage. ## How it works [#how-it-works] A nightly maintenance job runs in two phases: 1. **Archive** — data older than the retention window is compressed and written to cold storage, then removed from the live database. 2. **Downsample** — data that remains in the live database is thinned to progressively lower resolution as it ages. Full-resolution data is always preserved in the archive. If you need to query historical data at original resolution, it can be rehydrated on request. ## Retention windows [#retention-windows] Each data type has a retention window that controls how long it stays in the live database before being archived. | Data type | Retention window | Notes | | ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | | AIS positions | 90 days | Largest table by volume. Downsampled in place at 7 and 30 days, then archived raw to cold storage at 90 days. | | Port events | 60 days | Intelligence is also captured in vessel visits. | | Dark events | 90 days | AIS gap and dark activity detections. | | STS events | 90 days | Ship-to-ship transfer encounters. | | Loitering events | 90 days | Prolonged stationary vessel detections. | | Ingestion logs | 14 days | Internal pipeline telemetry. | Archived data is retained indefinitely at full resolution in cold storage. Only the live database copy is removed after the retention window. ## AIS position lifecycle [#ais-position-lifecycle] AIS positions move through four stages as they age. The first three stages keep data in the live database at progressively coarser resolution; the fourth moves raw data to cold storage. | Stage | Age range | Where it lives | Resolution | What it means | | ------- | ------------ | ----------------- | --------------- | ---------------------------------------------------------------------------------------- | | Live | 0–7 days | Live database | Full resolution | Every report is kept as received (often multiple per second). | | Tier 0 | 7–30 days | Live database | 1 per minute | One position per vessel per minute. Sufficient for route replay and behavioral analysis. | | Tier 1 | 30–90 days | Live database | 1 per 5 minutes | One position per vessel per 5-minute window. Useful for historical track review. | | Archive | Over 90 days | Cold storage (R2) | Full resolution | Raw rows are written to compressed JSONL and removed from the live database. | Data older than 90 days is preserved at full resolution in the archive — not downsampled. This means retrospective analyses that need fine-grained position history (for example, ship-to-ship transfer reconstruction or motif detection) can be answered at original resolution by rehydrating from the archive. ### Resolution impact [#resolution-impact] At full resolution, a single vessel broadcasting every 2 seconds produces approximately 43,000 position reports per day. After in-place downsampling: | Stage | Reports per vessel per day | | -------------- | -------------------------- | | Live | \~43,000 | | Tier 0 (1 min) | \~1,440 | | Tier 1 (5 min) | \~288 | | Archive (raw) | \~43,000 (in cold storage) | ## What this means for your queries [#what-this-means-for-your-queries] * **Real-time tracking and alerting** (0–7 days) — full resolution, no data loss. * **Recent investigations** (7–30 days) — 1-minute resolution is sufficient for route reconstruction, speed profiling, and anomaly detection. * **Historical analysis** (30–90 days) — 5-minute resolution shows vessel tracks and port visits clearly but may miss brief maneuvers. * **Long-term and retrospective analysis** (90+ days) — full-resolution data is available from the archive on request. Live-database queries do not return data older than 90 days; contact support to rehydrate the date range you need. ## Archive storage [#archive-storage] Archived data is stored in Cloudflare R2 as gzip-compressed JSONL, organized by table and date range. The archive retains full-resolution data indefinitely, so no information is permanently lost when records leave the live database. A daily cron runs at 03:00 UTC and archives any rows older than the retention window. AIS position archival is capped at 200,000 rows per run so that a backlog cannot starve the smaller archives (port events, transit metrics, POI snapshots) that share the same cron budget. At normal ingest volume the cap clears roughly two hours of historical raw positions per day, which is more than enough to keep up once the system reaches steady state. If you need to query archived data at its original resolution — for example, to reconstruct a vessel's exact track from several months ago — contact support to request a rehydration. ## Adjusting retention [#adjusting-retention] Retention windows are configured at the platform level and are not user-adjustable. If your use case requires longer hot retention (for example, keeping 90 days of full-resolution AIS positions for ongoing investigations), contact support to discuss options. # Get started with Overwatch (/overwatch/getting-started) Axiom Overwatch is a maritime intelligence platform that fuses AIS position data, vessel registry records, ownership chains, and sanctions lists into a single investigative workspace. In this guide you'll create a workspace, run your first vessel investigation, and share findings with your team — in about five minutes.

Axiom Overwatch vessel-monitoring dashboard: a live positions table, an anomaly feed, and key operational metrics for the Port of Santos geofence

## Prerequisites [#prerequisites] * A work email address (Overwatch workspaces are team-scoped) * A vessel identifier to investigate — an **IMO number** (7 digits), **MMSI** (9 digits), or vessel name ### Create your workspace [#create-your-workspace] Sign up at [app.axiomoverwatch.io](https://app.axiomoverwatch.io). Your workspace is private by default — invite teammates from **Settings → Members** when you're ready to collaborate. During onboarding you'll choose a workspace name and a default region. The region determines which AIS base stations and port-zone definitions are loaded first; you can change it later without losing data. ### Run an investigation [#run-an-investigation] From the dashboard, click **New investigation**. Paste an MMSI or IMO number into the search field and press Enter. Overwatch resolves the identifier against its vessel registry and pulls: * **Recent positions** — the last 30 days of AIS fixes, plotted on the live map with speed and course overlays * **Port calls** — detected arrivals and departures with berth-level matching where available * **Ownership chain** — registered owner, beneficial owner (UBO), and any sanctioned-party matches from OpenSanctions and OFAC lists * **Identity history** — prior names, flag changes, and MMSI changes that may indicate shell-hop activity If the vessel has been flagged by Overwatch's anomaly detectors (dark periods, route deviations, encounter activity), those signals appear as risk badges on the investigation header. ### Explore the live map [#explore-the-live-map] The investigation's position data is pre-loaded on the [live map](/overwatch/live-map). Use the timeline scrubber to replay the vessel's track, toggle AIS coverage overlays to see where satellite vs. terrestrial reception applies, and click any position fix for raw NMEA details. ### Save and share [#save-and-share] Investigations save automatically to your workspace's case files. From the case-file view you can: * **Share** with teammates via a workspace link * **Export to PDF** for external distribution or compliance records * **Link related investigations** to build a multi-vessel picture (e.g. a sanctioned owner's full fleet) ## What you'll see [#what-youll-see] After your first investigation, the dashboard surfaces: | Panel | What it shows | | ------------------------- | ----------------------------------------------------------------------------------------------------- | | **Active investigations** | Your open case files with last-updated timestamps | | **Risk feed** | New anomaly detections across your tracked vessels (dark events, spoofing alerts, encounter clusters) | | **Fleet overview** | If you've added multiple vessels, a summary of position freshness and flag distribution | | **Data health** | AIS feed latency and coverage gaps for your region | ## Next steps [#next-steps] Explore real-time vessel positions with AIS coverage overlays and timeline replay. Query vessel data from the command line with the Overwatch CLI. Integrate risk scores and anomaly detections into your own systems. Understand how Overwatch resolves entities, extracts encounters, and validates cargo estimates. Overwatch's data pipeline ingests AIS positions continuously and enriches them with registry, ownership, and sanctions data on a rolling basis. See [AIS coverage](/overwatch/ais-coverage) for reception details and [data retention](/overwatch/data-retention) for how long historical data is kept. # Axiom Overwatch (/overwatch) Sign up and run your first vessel investigation. Product overview, pricing, and case studies. ## From signal to decision [#from-signal-to-decision] Continue with [getting started](/overwatch/getting-started), the [live map](/overwatch/live-map), and the [API overview](/overwatch/api/overview). For weekly Overwatch release notes, see the [changelog](/changelog). # Live map (/overwatch/live-map) The live map displays real-time vessel positions across monitored ports. Each vessel appears as a directional triangle icon colored by vessel type, rotated to match its current course. You can filter by vessel type, search for specific ships, toggle map overlays, and replay a vessel's recent route. ## Open the live map [#open-the-live-map] Navigate to **Live Map** from the top navigation bar, or go directly to `axiomoverwatch.io/live-map`. To jump to a specific port, append the port slug to the URL — for example, `axiomoverwatch.io/live-map/santos` or `axiomoverwatch.io/live-map/rotterdam`. ## Vessel icons [#vessel-icons] Vessels appear as elongated triangle markers that point in the direction the vessel is travelling. The triangle shape follows the same 2.4:1 bow-forward silhouette used across the platform. Only vessels moving faster than 0.5 knots display a directional icon — slower or anchored vessels render as round dot markers instead, since course-over-ground readings are unreliable at low speed. Each vessel type has a distinct color: | Vessel type | Color | | ------------- | ---------------- | | Bulk carrier | Gold (#e5a836) | | Tanker | Cyan (#00D4FF) | | Container | Teal (#4a9e8e) | | LNG carrier | Purple (#8B5CF6) | | General cargo | Green (#7CB518) | | Other | Gray (#9CA3AF) | ## Vessel details [#vessel-details] **Hover** over a vessel to see a quick summary: name, type, IMO number, flag, speed, draft, and destination. **Click** a vessel to open a detailed popup that includes: * Vessel photo (when available) * IMO, flag, speed, draft, DWT, and build year * Reported destination * Recent port calls with arrival and departure times * Nearby weather conditions (temperature, wind speed, and direction) * A link to the full vessel intelligence page Free-tier accounts see the most recent port call. Upgrade to view the last five ports. ## Map controls [#map-controls] ### Vessel type filter [#vessel-type-filter] Use the vessel type filter to show or hide specific categories. All six types are enabled by default. Deselect a type to remove those vessels from the map. ### Vessel search [#vessel-search] Type a vessel name, IMO number, or keyword into the search bar to locate a specific ship. Results update as you type. Select a result to fly to the vessel's position on the map. ### Map style [#map-style] Switch between three base map styles (CARTO basemaps): * **Dark** — default style optimized for vessel visibility * **Light** — higher contrast for daytime use * **Voyager** — a balanced mid-contrast style with labeled geography ### Nautical chart overlay [#nautical-chart-overlay] Toggle the nautical chart overlay to display OpenSeaMap seamarks (buoys, lights, shipping lanes) on top of the base map. The overlay is available on both the MapLibre and Leaflet renderers. ### Course projection lines [#course-projection-lines] Enable course projection lines to display a dashed line ahead of each moving vessel, showing its projected position 30 minutes into the future based on current speed and heading. ### Port zones [#port-zones] Toggle port zones to display geofence, anchorage, and berth boundaries on the map. Zone labels appear at higher zoom levels. ### Vessel trails [#vessel-trails] Enable vessel trails to render the recent track of every vessel in the current viewport. Use the trail duration control to adjust how many hours of history are shown (up to 48 hours). ## 24-hour route replay [#24-hour-route-replay] Route replay is available only when viewing a port-specific map. Click a vessel and select **Replay 24h route** in the detail popup to animate the vessel's track over the past 24 hours. The replay draws the full route as a faded line and animates a highlighted path with a moving vessel marker that follows the recorded positions. Replay duration scales with the number of recorded positions (12–28 seconds). Click **Stop replay** in the replay banner to end the animation early. When no port is in scope, the replay button appears disabled in the detail popup with a prompt to select a port first. Open a port-specific view (for example, axiomoverwatch.io/live-map/santos) to enable route replay. ## Port-specific views [#port-specific-views] Each monitored port has a dedicated page at `axiomoverwatch.io/live-map/{port-slug}`. The port view opens the map centered on that port and displays a count of vessels currently in port. Available ports include Santos, Houston, New Orleans, Rotterdam, Singapore, Norfolk, Novorossiysk, Newcastle, Paranaguá, Port Hedland, Constanța, Hamburg, and Shanghai. ## Renderer fallback [#renderer-fallback] The live map uses MapLibre GL for hardware-accelerated rendering. If WebGL is unavailable or the basemap styles fail to load, the map automatically falls back to a Leaflet-based renderer with equivalent vessel icons drawn as SVG triangles. A banner at the top of the map indicates when the fallback renderer is active, and the map retries the primary renderer after 45 seconds. You can force the Leaflet renderer by appending `?renderer=leaflet` to the URL. Vessel data refreshes automatically every five minutes. When you pan or zoom the map, the visible vessels update to match the new viewport. # Status page (/overwatch/status-page) The Overwatch dashboard includes a status page that shows the real-time health of core platform services. Use it to check whether data pipelines are running normally or to diagnose why data might appear stale. ## What the status page shows [#what-the-status-page-shows] The status page displays the current state of four monitored services: | Service | What it checks | Warn threshold | | ------------------ | ------------------------------------------------ | --------------------- | | **Database** | Supabase connectivity and query latency | Query failure | | **AIS positions** | Freshness of the most recent AIS position report | Older than 60 minutes | | **Data pipeline** | Recency of the last completed ingestion job | Older than 2 hours | | **Visit pipeline** | Recency of the last departed vessel visit update | Older than 3 hours | Each service shows one of three states: * **Operational** — the service is healthy and data is fresh. * **Degraded** — the service is responding but data is stale beyond its expected threshold. * **Down** — the service failed its health check. ## 24-hour history [#24-hour-history] Below the current status, the page displays a visual timeline of health check results from the last 24 hours. Each colored bar represents a single check — green for operational, amber for degraded, and red for down. This makes it easy to spot intermittent issues or identify when a disruption started and resolved. ## How checks run [#how-checks-run] Health checks run automatically every 5 minutes. Each check records the service status, response latency, and any error details to the `service_uptime` table. The status page reads from this table to render the current and historical view. If a service fails three or more consecutive health checks, Overwatch logs an alert to the ingestion log so operators are notified. ## Health API endpoint [#health-api-endpoint] You can also query service health programmatically: ```bash curl https://your-overwatch-domain/api/health ``` The response includes a status summary and individual check results: ```json { "status": "healthy", "checks": { "db": { "status": "ok", "latency_ms": 45 }, "ais_positions": { "status": "ok", "latency_ms": 120 }, "ingestion_logs": { "status": "ok", "latency_ms": 85 } }, "timestamp": "2026-04-20T12:00:00.000Z" } ``` The endpoint returns: * `200` with `"status": "healthy"` when all checks pass. * `200` with `"status": "degraded"` when some checks return warnings but none have failed. * `503` with `"status": "unhealthy"` when any check has failed. You can use this endpoint for load balancer probes or external uptime monitoring tools. ## Worker heartbeats [#worker-heartbeats] In addition to the platform-level service checks above, long-running ingestion workers report periodic heartbeats so you can verify that each worker is alive and processing data. Heartbeats are visible on the cockpit **Workers** view alongside the headline status page. | Worker | Beat interval | Reported metadata | | -------------------------- | -------------------- | ------------------------------------------------------------------------ | | `overwatch-ais-ingest` | 60 seconds | Positions ingested, vessels upserted, buffer size, circuit-breaker state | | `overwatch-equasis-direct` | Per enrichment cycle | Account in use, vessels enriched, vessels failed | | `overwatch-equasis-vpn` | Per enrichment cycle | Account in use, vessels enriched, vessels failed | | `overwatch-scraper` | 60 seconds | Jobs completed, jobs failed | Each beat records a timestamp and a small JSON payload of the worker's most recent counters. The cockpit computes uptime over a rolling window from these beats and flags workers as **stale** when beats stop arriving — typically a sign that the underlying service has crashed or lost connectivity even though the platform-level checks above still report healthy. Heartbeats are best-effort: failures to record a beat are logged but never crash the worker itself, so a cockpit outage cannot take down ingestion. ## Accessing the status page [#accessing-the-status-page] Navigate to **Dashboard > Status** in the Overwatch web application. The page is available to all authenticated users. # Terminal (/overwatch/terminal) The Overwatch terminal is a Bloomberg-style heads-up display at [`/dashboard`](https://app.axiomoverwatch.io/dashboard). It replaces the scrollable landing page with a fixed-viewport grid of six panels per mode, function-key navigation, a command palette, and per-user pinning — so a single screen tells you what's moving across global vessel traffic right now. Use the terminal when you want to monitor maritime activity continuously rather than browse one report at a time. The legacy dashboard is preserved at [`/dashboard/overview`](https://app.axiomoverwatch.io/dashboard/overview) for users who prefer the original layout. ## Modes [#modes] The terminal has two modes that you can swap between without leaving the page: | Mode | Purpose | URL | | --------- | ------------------------------------------------- | --------------------------------- | | **TRADE** | Commodity flow, port throughput, and forecasts | `/dashboard?mode=trade` (default) | | **SANC** | Sanctions, dark-fleet behavior, and risk profiles | `/dashboard?mode=sanc` | Each mode renders six panels in a fixed 12-column, 2-row grid sized to the viewport. The grid never scrolls — every panel scrolls independently inside its own frame. ### TRADE panels [#trade-panels] | ID | Panel | What it shows | | --- | ------------------ | ---------------------------------------------------------------------------------------- | | A01 | Port flow heatmap | Current vs. prior-week tonnage delta across all tracked ports | | A02 | Live vessel map | All ports with known coordinates, sized by active vessels and tonnage | | A03 | Export forecast | Top ports by upcoming weekly tonnage, with a 6-week sparkline | | A04 | Berth utilization | Latest occupancy per berth zone with weekly trend direction | | A05 | Commodity tape | Most recent vessel visits with cargo guess and tonnage estimate | | A06 | Trade-flow tracker | Top export flows by net weight from the [trade-flow dataset](/overwatch/api/trade-flows) | ### SANC panels [#sanc-panels] | ID | Panel | What it shows | | --- | ------------------ | -------------------------------------------------------------------------------------- | | B01 | Active alerts | Last 24 hours of [alerts](/overwatch/api/alerts) across your workspace | | B02 | Dark fleet map | Vessels with dark events in the last 7 days | | B03 | Anomaly queue | Ports with active [anomalies](/overwatch/api/risk) flagged | | B04 | Risk profiles | High-watch vessels with [risk scores and tiers](/overwatch/api/risk) | | B05 | Verification queue | Spoofing candidates that need analyst review | | B06 | Recent events | Dark gaps, STS encounters, identity changes, draft mismatches, loitering — last 7 days | ## Keyboard navigation [#keyboard-navigation] The footer renders a function-key bar that mirrors the legacy desktop terminal experience. Each key opens a deep-link route, so you can jump to a full-page detail view without leaving the keyboard: | Key | TRADE | SANC | | --- | ------------------ | ------------------ | | F1 | Command palette | Command palette | | F2 | Ports / congestion | Alerts | | F3 | Forecasts | Anomalies | | F4 | Routes | Risk | | F5 | Berth utilization | Exceptions | | F6 | LNG | Fleet age | | F7 | Mining | Fleet intelligence | | F8 | Containers | Vessel lookup | | F9 | Earnings | Watchlist | | F10 | Trade flows | Sanctions | | F11 | Watchlist | Status | | F12 | Legacy dashboard | Legacy dashboard | Press ⌘K (or Ctrl+K on Windows and Linux) to open the command palette from anywhere in the terminal. The palette searches all panels, mode switches, and detail routes, with the matching function-key shortcut shown next to each entry. ## Pinning vessels [#pinning-vessels] Both the **Risk profiles** (B04) and **Recent events** (B06) panels expose a pin action on each vessel row. Pinning a vessel by IMO writes through to your [watchlist](/overwatch/api/watchlist) — the same list that backs alerts and the standalone watchlist view — so a vessel you pin from the terminal also starts receiving the watchlist's default notifications: * `port_entry` * `port_departure` * `dark_event` * `sanctions_match` Pinned vessels render with a highlighted bar across every panel that knows about IMO numbers, and the **Risk profiles** subtitle shows your total pin count. To unpin, click the pin icon again or remove the entry from the watchlist UI. ## Mobile view [#mobile-view] On viewports below the desktop breakpoint, the terminal swaps to a stripped-down mobile layout that surfaces the highest-signal data from the active mode: * **TRADE mobile** — top 8 ports by absolute weekly delta, top 6 forecasted ports, plus aggregate counters for total tonnage, active vessels, and active ports. * **SANC mobile** — top 8 alerts, top 6 high-watch risk vessels, plus counters for 24-hour alerts, 7-day flagged fleet, and active anomalies. The function-key bar and command palette are hidden on mobile because they assume a physical keyboard. Tap any row to open the corresponding detail route. ## Programmatic access [#programmatic-access] Every panel is backed by an existing public API. You can replicate the terminal's data feeds in your own dashboard or workflow by calling these endpoints directly: ```bash # TRADE mode curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/congestion curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/forecasts curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/berth curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/trade-flows # SANC mode curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/alerts curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/risk curl -H "X-API-Key: YOUR_KEY" https://www.axiomoverwatch.io/api/v1/watchlist ``` See the [API reference](/overwatch/api/overview) for full request and response schemas. ## When to use the terminal vs. the legacy dashboard [#when-to-use-the-terminal-vs-the-legacy-dashboard] | Use the terminal when | Use the [legacy dashboard](https://app.axiomoverwatch.io/dashboard/overview) when | | ----------------------------------- | --------------------------------------------------------------------------------- | | You want every signal on one screen | You prefer scrollable, vertical layouts | | You navigate by keyboard | You navigate by mouse and tap | | You're monitoring continuously | You're running a one-off investigation | | You're on a wide desktop display | You're on a narrow window or iframe | Both views read from the same data, so any vessel you pin or any alert you acknowledge is reflected immediately in the other. # Billing (/routeshift/billing) RouteShift charges 3% of measured savings — see [Savings & pricing](/routeshift/savings-and-pricing) for the full mechanics. This page covers what you see in the dashboard, how invoices are produced, and how to slice spend across keys. ## Spend breakdown [#spend-breakdown] The **Billing → Spend** page shows total workspace spend with three breakdowns: * **By virtual key** — every key ranked by 30-day spend, with request count and a sparkline. Drill into any key to see the underlying request log. * **By metadata tag** — group by any tag dimension (`env`, `customer`, `agent`, `experiment`, etc.). Useful for chargebacks or per-customer attribution. * **By model** — every model that produced spend, with mean cost per request and total tokens. The companion view at `/models/compare` lets you A/B alternatives. All numbers are computed in microcents and rendered as USD with millicent precision so small calls aggregate without rounding error. ## Plans [#plans] RouteShift ships a **single tier**: 3% of measured savings, no monthly fee, no seat fee, no minimum. A generous free tier covers low-volume usage at zero cost. For organizations that need invoicing, custom retention, or BYO Stripe — contact [sales@routeshift.io](mailto:sales@routeshift.io). Otherwise, billing is fully self-serve through the Stripe customer portal. ## Stripe customer portal [#stripe-customer-portal] Open **Billing → Manage** to launch the Stripe-hosted portal. From there you can: * Update payment method. * Download past invoices. * Cancel the subscription (data and keys are retained; new requests stop billing immediately). * View upcoming invoice with line items linked to the underlying request logs. ## Permissions [#permissions] Only **Owner** and **Admin** roles ([see Team & access](/routeshift/team)) can start checkout or open the customer portal. The dashboard routes are `POST /api/billing/checkout` and `POST /api/billing/portal`; unauthenticated users and members receive `403 Forbidden — admin or owner required`. The role check runs before Stripe customer state is touched. A team with an existing live non-promo subscription is sent to the portal instead of creating a second checkout. ## How invoices line up with usage [#how-invoices-line-up-with-usage] Every monthly invoice contains a single line item — "RouteShift savings share" — with the following metadata: * `period_start` / `period_end` — calendar month boundaries (UTC). * `gross_savings_microcents` — total savings produced in the period. * `share_rate` — currently `0.03`. * `audit_url` — link back to the dashboard's billing breakdown for that month. The audit URL is durable: if you ever need to reconcile a charge, the underlying request logs are preserved for the lifetime of the workspace. # Budgets & alerts (/routeshift/budgets) Every virtual key can carry a monthly USD budget. RouteShift enforces it server-side: a soft threshold fires a notification, the hard cap blocks new requests until the next monthly reset, and a projected-overrun model alerts you before either trips. ## Budget mechanics [#budget-mechanics] Budgets are stored in **microcents** (1/10,000th of a cent) so even fractional-cent calls aggregate cleanly. Each request decrements the running monthly total atomically; on the first day of each calendar month (UTC) the running total resets to zero. For a key with a $50 monthly budget and an 80% soft-alert threshold: | State | Behavior | | ------------ | ----------------------------------------------------------------------------------------------------------- | | 0–80% used | Normal traffic. No alerts. | | 80–100% used | Soft alert fires once per threshold crossing (email, Slack, or webhook). Traffic continues. | | 100% used | Hard cap. New requests return `429` with `X-RouteShift-Reason: budget_exceeded`. In-flight requests finish. | | Reset | At 00:00 UTC on day 1, the running total drops to zero and the key resumes serving. | ## Setting a budget [#setting-a-budget] ### Open key settings [#open-key-settings] Navigate to **Settings → Keys** and click the key you want to cap. Each key shows its current month-to-date spend and remaining budget inline. ### Set the monthly cap [#set-the-monthly-cap] Enter a USD amount in the **Monthly budget** field. The value is stored internally in microcents, so $50.00 becomes 500,000,000 microcents — you never need to think about the internal representation. ### Configure the soft threshold [#configure-the-soft-threshold] Set the alert threshold as a percentage (default: 80%). When spend crosses this line, RouteShift fires a notification to every configured channel. The alert fires **once per crossing** — it won't spam you on every request after the threshold. ### Choose alert channels [#choose-alert-channels] At **Settings → Notifications**, configure where budget alerts go: email, Slack incoming webhook, or a generic JSON webhook. You can enable all three simultaneously. ## Projected-overrun alerts [#projected-overrun-alerts] In addition to the hard/soft thresholds, RouteShift fits a linear trend to the trailing 7 days of spend and projects month-end usage. If the projection exceeds the budget — even though current usage is still under the soft threshold — a **projected overrun** alert fires once per key per month. This catches sudden ramps before they hit the cap. The projection is shown on the **Billing → Budgets** page as a dotted forecast line over the actual spend curve. ### How the projection works [#how-the-projection-works] The model is intentionally simple — a least-squares linear fit on the trailing 7 days of daily spend, extrapolated to the last day of the current month. It's not a time-series forecast; it's a "if this trend continues, where do we land?" sanity check. | Scenario | Projection behavior | | -------------------------------- | --------------------------------------------------------------------------------- | | Steady daily spend | Projects linearly; accurate for stable workloads | | Sudden ramp (new agent deployed) | Catches the ramp within 2–3 days of data | | One-time spike (backfill job) | May over-project; the alert fires once and won't repeat unless the trend sustains | | Mid-month budget increase | Projection recalculates against the new budget on the next daily rollup | ## Multi-tier alerts [#multi-tier-alerts] Configure where alerts go at **Settings → Notifications**: * **Email** — to the workspace owner and any address on a mailing list. * **Slack** — via incoming webhook; the alert message includes the key name, percent used, and a deep link to the billing page. * **Webhook** — POST `application/json` payload with `{ key_id, threshold, used_microcents, budget_microcents, period }`. Useful for routing into an oncall system. ### Webhook payload [#webhook-payload] ```json { "key_id": "vk_a1b2c3d4", "key_name": "production-agent", "alert_type": "soft_threshold", "threshold_pct": 80, "used_microcents": 4000000000, "budget_microcents": 5000000000, "period": "2026-07", "projected_month_end_microcents": 6200000000, "dashboard_url": "https://app.routeshift.io/billing/budgets?key=vk_a1b2c3d4" } ``` The `alert_type` field is one of `soft_threshold`, `hard_cap`, or `projected_overrun`. The `projected_month_end_microcents` field is included on all alert types so your oncall system can distinguish "we're at 80%" from "we're at 80% *and trending to 124%*". ## Workspace-wide rollups [#workspace-wide-rollups] Beyond per-key budgets, the **Billing → Spend** view shows total workspace spend with the same projected-overrun model applied at the org level. Use it to set a rough business cap separate from per-key safety nets. Budgets are a safety net, not a forecasting tool. For accurate forecasts, pair budgets with the [Optimize page](/routeshift/optimize) to remove waste before it shows up in the trend line. # File parser (/routeshift/file-parser) The **file parser plugin** lets any chat completion accept PDF file parts alongside the usual `text`/`image` content. RouteShift decodes each PDF, enforces per-file and per-request byte, page, and text-length budgets, and replaces the raw file with either extracted text or a validated native-PDF part before dispatching upstream. Like [web search](/routeshift/web-search), file parsing runs entirely proxy-side. You don't need to swap providers or bolt on a document-extraction service — any model you can call through RouteShift can accept a PDF. ## When to use it [#when-to-use-it] Turn on file parsing when a user turn (or system prompt) needs to reference the contents of a PDF — a report the user uploaded, a spec pulled from a URL, a receipt, a contract. The plugin is a good fit for: * Client apps that already send OpenAI-style `input_file` parts and want the same shape to work across every provider RouteShift routes to. * Workflows that hand the model a URL to a PDF instead of pre-extracting text. * Multi-provider setups where you want fail-closed passthrough on Anthropic and Gemini (native PDF understanding) with automatic text fallback everywhere else. Skip it for non-PDF documents (unsupported today), for images (use the provider's native image parts), or when your prompt is already text. ## Opt in per request [#opt-in-per-request] The file parser is triggered in one of three ways: 1. **A `file` or `input_file` content part** on any user message. The plugin runs automatically as soon as a request contains one — no `plugins` array entry is required. 2. **An explicit `plugins` entry** with `id: "file-parser"`. Use this when you want to mark the plugin as `required` (so a parse failure short-circuits the request instead of degrading), or to force text extraction on a provider that would otherwise get native PDF passthrough. 3. **A `file` part inside the `system_prompt`**. System documents are always extracted to text, regardless of the target provider. The `plugins` array is stripped from the payload before dispatch — upstream providers never see it. ### Base64 inline PDF [#base64-inline-pdf] ```bash curl https://api.routeshift.io/v1/chat/completions \ -H "Authorization: Bearer sk-proxy-…" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Summarize the attached research paper in three bullets." }, { "type": "file", "filename": "paper.pdf", "file": { "file_data": "data:application/pdf;base64,JVBERi0xLjQK…" } } ] } ] }' ``` ### URL-backed PDF [#url-backed-pdf] ```json { "model": "gemini-3.1-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What are the top three risks in this filing?" }, { "type": "file", "filename": "10-k.pdf", "file": { "file_url": "https://example.com/reports/10-k.pdf" } } ] } ] } ``` ### Explicit plugin entry (mark as required, or force text extraction) [#explicit-plugin-entry-mark-as-required-or-force-text-extraction] ```json { "model": "claude-sonnet-5", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Extract the invoice total and due date." }, { "type": "file", "filename": "invoice.pdf", "file": { "file_data": "data:application/pdf;base64,…" } } ] } ], "plugins": [ { "id": "file-parser", "required": true } ] } ``` An explicit `file-parser` entry also **opts out of native PDF passthrough** — every file goes through the text-extraction path even when the target provider natively supports PDFs. Use this when you want consistent, provider-agnostic text output. ## Supported inputs [#supported-inputs] The plugin accepts either `file` or `input_file` content parts. The PDF payload can be provided as: | Field | Where | Format | | ------------------ | -------------------------------- | ----------------------------------------------------------- | | `file_data` | top level or nested under `file` | Raw base64, or a `data:application/pdf;base64,…` URI | | `file_url` / `url` | top level or nested under `file` | `https://` URL that returns `Content-Type: application/pdf` | A `filename` (or `name`) may be supplied at the top level or nested under `file`; RouteShift sanitizes it before forwarding — non-alphanumeric characters become underscores, and the length is capped. If no filename is supplied, `document.pdf` is used. Only PDFs (`application/pdf` with a `%PDF-` magic header) are accepted. Anything else surfaces an `unsupported_file_type` warning. ## Native PDF passthrough vs. text extraction [#native-pdf-passthrough-vs-text-extraction] RouteShift picks between two output shapes for each user-message file part: * **Native PDF passthrough.** When the resolved target model — *and every model in the fallback chain* — is explicitly marked as supporting native PDF (currently Claude and Gemini families), the plugin forwards a bounded, validated PDF part directly to the provider. This preserves layout, tables, and figures that text extraction would lose. * **Text extraction.** In every other case, the plugin extracts text with a page-count cap and replaces the file part with a `text` part of the form `[Extracted from ]\n`. The switch is **fail-closed**: native passthrough only kicks in when the primary route *and* every possible fallback candidate for the request supports it. Any mixed chain falls back to text extraction so the request never depends on an untested adapter. System-prompt files are always text-extracted regardless of provider. An explicit `file-parser` plugin entry (see above) forces text extraction as well. ## Budgets and limits [#budgets-and-limits] Every request runs against a set of per-file and per-request budgets. All of them are configurable per-deployment; the defaults are: | Budget | Default | Env var | What it protects | | -------------------------------- | ----------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Files per request | `10` | `PLUGIN_MAX_FILES` | Total file-part attempts, including malformed URLs and base64 (attempted before any validation, so a burst of broken inputs can't bypass this cap). | | Bytes per file | `10 MiB` | `PLUGIN_MAX_FILE_BYTES` | Decoded PDF size after base64 or download. | | Pages per file | `100` | `PLUGIN_MAX_FILE_PAGES` | Declared page count; exceeding the cap fails the file rather than silently truncating. | | Extracted text per file | `1,000,000` chars | `PLUGIN_MAX_EXTRACTED_TEXT_CHARS` | Text extracted from a single PDF. | | Total bytes per request | `10 MiB` | `PLUGIN_MAX_TOTAL_FILE_BYTES` | Sum of decoded bytes across every file in the request. | | Total extracted text per request | `1,000,000` chars | `PLUGIN_MAX_TOTAL_EXTRACTED_TEXT_CHARS` | Sum of extracted text across every file. | | Fetch timeout | `5000` ms | `PLUGIN_FETCH_TIMEOUT_MS` | Single URL-fetch deadline (DNS + transport combined). | Every fetch error conservatively **exhausts** the request's remaining byte budget: a failed request can already have read a partial body, and the plugin can't know how much. That's deliberate — it makes each file attempt a hard, all-or-nothing charge against the aggregate cap. ## Optional vs. required plugins [#optional-vs-required-plugins] The file parser is **optional by default**. When a file can't be parsed — the URL was blocked, the payload was too large, the content type wasn't PDF, extraction failed — the request continues without the file, and a `PluginWarning` is attached to the response and the request log. Set `"required": true` when the model shouldn't answer without the file. A required-plugin failure short-circuits the request with: ```http HTTP/1.1 502 Bad Gateway Content-Type: application/json { "error": { "code": "plugin_required_failed", "message": "Required plugin file-parser failed: " } } ``` ## Warning codes [#warning-codes] Each warning surfaces as `{ plugin: "file-parser", code: "

" }` on the response and is persisted in the request log's plugin-run audit row. Codes are stable and deliberately do **not** include filenames, URLs, or response bodies.

| Code                    | Meaning                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `file_url_blocked`      | URL resolved to a private/loopback/link-local address, an unsupported scheme, or was blocked by SSRF checks.                                     |
| `file_too_large`        | Exceeded a per-file or per-request byte/page/text budget.                                                                                        |
| `unsupported_file_type` | Not a PDF (bad magic bytes or content type), or neither `file_data` nor `file_url` was supplied.                                                 |
| `empty_file`            | PDF parsed successfully but contained no extractable text (common for scanned image-only documents when native PDF passthrough isn't available). |
| `file_parse_failed`     | Decoder rejected the payload.                                                                                                                    |
| `file_fetch_failed`     | URL fetch returned a non-2xx status, a bad redirect, or a non-PDF content type.                                                                  |
| `file_fetch_timeout`    | URL fetch didn't complete within `PLUGIN_FETCH_TIMEOUT_MS`.                                                                                      |

## Security [#security]

URL-backed PDFs are fetched through RouteShift's SSRF-safe fetch path: every candidate address is validated and DNS-pinned before transport, so a URL cannot rebind to a private address between the check and the connection. Loopback, IPv4 private/special-use ranges, ULA, link-local and site-local IPv6, multicast, discard-only, IPv4-embedded IPv6, and NAT64 forms are all rejected. Redirects are followed up to three hops and re-validated at each hop.

Filenames are sanitized before they reach an upstream provider. Extracted text is wrapped with a clearly labeled `[Extracted from ]` header so the model treats the content as supplied context, not authoritative instructions.

## Billing and audit [#billing-and-audit]

Every plugin execution — file parser included — writes a sanitized audit row that captures the plugin id, status (`ok` / `warning` / `error` / `skipped`), a stable detail code, cost, and latency. Rows are keyed by `(request_id, plugin_id)` and are visible in your [observability feed](/routeshift/observability) alongside the underlying request.

The file parser itself does not add a per-request surcharge — the cost of extraction is folded into the request. Plugin surcharges (currently applied by [web search](/routeshift/web-search)) are tracked separately from provider model cost so plugin fees never get relabeled as routing spend. See [Savings and pricing](/routeshift/savings-and-pricing) for how the two components appear in usage reports.

## Errors [#errors]

| Response                 | Status | When                                                                                                             |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `invalid_plugin`         | 400    | `plugins` isn't an array, contains a non-object entry, or references an unsupported plugin id.                   |
| `file_*` (warning)       | 200    | Optional file parser skipped a file for one of the codes above. Underlying model response is delivered normally. |
| `plugin_required_failed` | 502    | A `required: true` file-parser plugin couldn't process a file — no upstream call was made.                       |


# Get started with RouteShift (/routeshift/getting-started)




  



  
    ### Create your workspace [#create-your-workspace]

    Sign up at [app.routeshift.io](https://app.routeshift.io). You'll need an admin email — a personal email is fine for solo accounts.
  

  
    ### Add a provider key [#add-a-provider-key]

    Open **Settings → Providers** and paste in at least one upstream key (OpenAI, Anthropic, or any of the [supported providers](/routeshift/providers)). RouteShift encrypts the key at rest with `PROVIDER_KEY_SECRET` and never returns the plaintext after save.
  

  
    ### Mint a virtual key [#mint-a-virtual-key]

    Open **Keys → Create key**. Optionally set:

    * **Allowed models** — restrict which models this key can call.
    * **Expires at** — auto-revoke on a calendar date.
    * **RPM / TPM** — per-key requests- and tokens-per-minute caps.
    * **Monthly budget** — hard cap with optional soft-alert threshold.
    * **Metadata** — arbitrary `key=value` tags for cost attribution.

    The dialog returns a one-time `sk-proxy-…` token. Copy it immediately — RouteShift hashes it on save and cannot show it again.
  

  
    ### Proxy your first request [#proxy-your-first-request]

    RouteShift is OpenAI-compatible. Any client that takes a base URL works — swap `https://api.openai.com` for `https://api.routeshift.io` and use your `sk-proxy-…` key:

    
      
        ```bash cURL
        curl https://api.routeshift.io/v1/chat/completions \
          -H "Authorization: Bearer sk-proxy-…" \
          -H "Content-Type: application/json" \
          -d '{
            "model": "gpt-4o-mini",
            "messages": [{"role": "user", "content": "hello"}]
          }'
        ```
      

      
        ```ts TypeScript SDK
        import { ProxyClient } from "@routeshift/sdk";

        const client = new ProxyClient({
          baseUrl: "https://api.routeshift.io",
          apiKey: "sk-proxy-…",
        });

        const res = await client.chat({
          model: "gpt-4o-mini",
          messages: [{ role: "user", content: "hello" }],
        });
        ```
      

      
        ```py Python (OpenAI drop-in)
        from openai import OpenAI

        client = OpenAI(
            base_url="https://api.routeshift.io/v1",
            api_key="sk-proxy-…",
        )

        res = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": "hello"}],
        )
        print(res.choices[0].message.content)
        ```
      
    
  

  
    ### Review the request log [#review-the-request-log]

    Open **Activity**. The request appears within seconds with tokens, cost in microcents, latency, the resolved upstream model, and an inferred [activity category](/routeshift/observability#activity-categorization).
  



  Need help? Email [support@routeshift.io](mailto:support@routeshift.io).



# RouteShift (/routeshift)








  
    Sign up, mint your first key, and proxy your first request.
  

  
    Pricing, providers, and the savings-share model.
  


## How a request flows [#how-a-request-flows]

RouteShift exposes an OpenAI-compatible client surface at
`https://api.routeshift.io/v1`. The deployed public routes cover chat
completions, embeddings, models, and model detail.



## What RouteShift covers [#what-routeshift-covers]

* **Virtual API keys** — `sk-proxy-` keys with per-key allowed models, RPM/TPM limits, monthly budgets, expiry, metadata tags, rotation with grace periods, and a full audit trail.
* **Routing & fallbacks** — rules that pick a target model (or a chain), with model aliases, weighted load balancing across N provider keys, latency-based and least-busy strategies, and automatic 5xx/429 cooldowns.
* **Observability** — every request is logged with tokens, cost, latency, and an inferred activity category. Sessions are stitched together for one-shot vs. retry-rate analysis and side-by-side model comparison.
* **Optimize findings** — a static-analysis pass over recent traffic that flags duplicate prompts, oversized system prompts, model-mismatch waste, and other cost leaks.
* **Spend & savings** — pricing pulled directly from the LiteLLM JSON catalog, monthly per-key budgets with projected-overrun alerts, per-key cost attribution in the billing breakdown, and a 3% savings-share monetization model.


  BYOK is the default: you bring provider keys, RouteShift never resells inference.


RouteShift ships weekly — follow release notes in the [changelog](/changelog).


# Virtual API keys (/routeshift/keys)



A **virtual key** is a `sk-proxy-…` token your application uses to call RouteShift. It maps to one or more **provider keys** (the actual upstream credentials) but never exposes them. Every key has its own controls — model allowlist, rate limits, budget, expiry, and metadata — so you can hand out scoped keys per environment, customer, agent, or experiment without minting upstream credentials.




  For interactive CLIs and per-employee credentials, use the [SSO device flow](/routeshift/sso-device-flow) — employees self-issue short-lived keys by signing in to Google Workspace or Okta, with no admin involvement.


## Per-key controls [#per-key-controls]

| Control            | Behavior                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allowed models** | Whitelist of model IDs (or `*` for all). Requests outside the list are rejected with `403`.                                                                  |
| **Expires at**     | Calendar date after which the key is auto-revoked. Existing requests in flight finish; new ones return `401`.                                                |
| **RPM**            | Requests-per-minute cap, enforced in an isolated bucket per key. Overrides any team-level RPM.                                                               |
| **TPM**            | Tokens-per-minute cap, summed across input + output tokens. Bursty long-context calls are throttled before they reach upstream.                              |
| **Monthly budget** | Hard USD cap (microcent-precision). Soft-alert threshold (default 80%) fires a notification; reaching 100% blocks new requests until the next monthly reset. |
| **Metadata**       | Arbitrary `key=value` pairs. Used by `/billing` to break down spend by environment, customer, or any other dimension.                                        |

All values can be set when minting the key (Keys → Create key) or edited later from **Keys → … → Edit**. Edits apply to new requests immediately.

## Key lifecycle [#key-lifecycle]

Every state change is recorded in **Keys → … → Audit log**: created, edited, rotated, revoked, expired. Audit events include the actor (user ID), timestamp, and a diff of the changed fields. The log is append-only and exposed via the [admin API](/routeshift/api/admin) for backup or SIEM forwarding.

## Key rotation with a grace period [#key-rotation-with-a-grace-period]

When a key is compromised — or you just want to roll credentials on a schedule — use **Keys → … → Rotate**. RouteShift mints a new `sk-proxy-…` token, marks the old one as `rotated`, and keeps it valid for a configurable grace window (default 24 hours). During the grace window, both tokens accept traffic, so you can deploy the new value without downtime. After the window closes, the old token returns `401`.

## Cost attribution [#cost-attribution]

Per-key spend is computed from the [LiteLLM pricing catalog](/routeshift/savings-and-pricing) and rolled up nightly. The **Billing → Spend breakdown** view lets you slice spend by:

* Virtual key
* Metadata tag (e.g. `env=prod`, `customer=acme`, `agent=research`)
* Provider
* Model
* Activity category

Each row shows total cost, request count, mean tokens, and a 30-day sparkline.


  Tag keys at create time with whatever dimensions you bill on. RouteShift never indexes the metadata for routing — it's purely for downstream analytics.



# Observability (/routeshift/observability)



RouteShift logs every request — input tokens, output tokens, cost, latency, resolved upstream model, and an inferred activity category — into `request_logs`. From there, downstream tables stitch sessions, score turn signals, and roll up per-session metrics for the dashboard.



## What gets logged [#what-gets-logged]

Every proxied request writes one row containing:

* Virtual key ID and provider key ID.
* Requested model + resolved upstream model (after aliases and routing).
* Input tokens, output tokens, total cost (microcents).
* Wall-clock latency, time-to-first-token, and upstream HTTP status.
* Inferred [activity category](#activity-categorization).
* Stitched [session ID](#session-stitching) and [turn signals](#turn-signals).
* Cache-hit flag (semantic cache hits skip token-counting and write `[]` / `false` for turn signals).

Logs are queryable from the dashboard's **Activity** view and exposed via the [admin API](/routeshift/api/admin) for ETL into your warehouse.

## Activity categorization [#activity-categorization]

RouteShift classifies each request into one of these categories based on the prompt shape and model behavior:

* `chat` — interactive single-turn or short multi-turn dialog.
* `agentic` — long tool-use chains, multi-turn with structured output.
* `code` — code generation, refactoring, or completion.
* `research` — long-context summarization or analysis.
* `embedding` — embedding model calls.
* `other` — anything that doesn't match the above.

Categorization happens in the proxy, server-side, on the request path. The classifier is deterministic — same input always produces the same category — so categories are safe to use as analytics dimensions.

## Session stitching [#session-stitching]

A **session** is a sequence of requests from the same virtual key that share contextual signals (continuation of a conversation, same `session_id` metadata, contiguous timestamps, similar prompts). RouteShift derives a session ID via `deriveSessionId` and writes it into `request_logs.session_id`. The aggregator (`session-aggregator.ts`) rolls those rows into `session_metrics` every five minutes, behind a `pg_try_advisory_xact_lock` so it's safe to run on replicas.

`session_metrics` powers:

* **Overview KPI** — total sessions, mean tokens per session, mean cost per session.
* **Analytics by-model table** — per-model session counts, one-shot rate, retry rate.
* **Activity drill-in** — click any row in the activity feed to see all requests in that session.

## Turn signals [#turn-signals]

Each request can be tagged with structured turn signals that describe what happened:

* `edited_paths text[]` — file paths the model edited (when integrated with a coding agent).
* `had_bash boolean` — whether the turn ran a shell command.

These are surfaced in the session view and used by the [Optimize engine](/routeshift/optimize) to detect duplicate or wasteful turns.

## One-shot rate and retry rate [#one-shot-rate-and-retry-rate]

Two derived metrics capture how efficient a session was:

* **One-shot rate** — fraction of sessions where the user got a usable response on the first turn. High one-shot rate means the model is sized correctly for the task.
* **Retry rate** — fraction of turns where the user re-prompted (manual retry) within a short window. High retry rate is a leading indicator of model mismatch.

The dashboard exposes both metrics at `GET /api/usage/one-shot` for signed-in team members and breaks them down by model. This is a dashboard-origin route; it is not authenticated with the proxy's `ADMIN_SECRET`.

## Model comparison [#model-comparison]

`/models/compare` plots two models side by side on the same traffic — same activity categories, same prompt sizes — and shows the cost / latency / one-shot-rate delta. Use it to A/B a candidate downgrade before flipping a routing rule.


# Optimize findings (/routeshift/optimize)



The Optimize page runs a recurring pass over the last 7 days of `request_logs` and produces concrete findings — each with an estimated monthly $ impact and a one-click fix path.



## Finding types [#finding-types]

| Finding                     | What it detects                                                                               | Typical fix                                            |
| --------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Oversized system prompt** | System prompts above a per-model size threshold that don't measurably improve output quality. | Trim the prompt or cache the system block.             |
| **Duplicate requests**      | Identical or near-identical prompts repeated within a short window from the same key.         | Add idempotency or a client-side cache.                |
| **Model mismatch**          | Tasks classified as `chat` running on frontier models, or `agentic` running on small models.  | Re-route via a rule.                                   |
| **Underused budget**        | Keys with monthly budgets that haven't been touched in 30+ days.                              | Lower the budget or revoke.                            |
| **Stuck in retry loop**     | Sessions with retry rate > 50% on the same model.                                             | Compare against a stronger model in `/models/compare`. |

### How findings are classified [#how-findings-are-classified]

The analyzer uses a combination of structural and statistical signals:

* **Oversized prompt** — flags requests where the system prompt exceeds the model-specific token threshold (e.g. 4,000 tokens for `gpt-4o-mini`, 8,000 for `gpt-4o`) *and* the response quality metrics (completion length, stop reason) don't correlate with the prompt size. A 12,000-token system prompt that produces the same output as a 2,000-token version is a trim candidate.
* **Duplicate requests** — hashes the prompt content (system + user messages) and flags clusters of 3+ identical hashes within a 60-second window from the same virtual key. Near-duplicates (Jaccard similarity > 0.95 on the message array) are also flagged.
* **Model mismatch** — classifies each request's task type from the message structure (single-turn chat, multi-turn conversation, tool-use/agentic, code generation) and compares against the model's intended use case. A single-turn "what's the capital of France?" running on `o3` is a mismatch.
* **Stuck in retry** — tracks per-session retry rates and flags sessions where more than half the attempts hit the same model with the same error class (typically `429` or `500`).

## How estimates are calculated [#how-estimates-are-calculated]

Each finding ships with a projected monthly $ savings, computed from:

* The volume of matching requests in the last 7 days.
* The cost delta between the current model and the suggested target (priced from the [LiteLLM catalog](/routeshift/savings-and-pricing)).
* A 30-day projection assuming current traffic patterns hold.

Estimates are conservative — RouteShift floors negatives to zero and ignores findings under $1/month so the page only surfaces work worth doing.

## Acting on a finding [#acting-on-a-finding]

Each card has an **Apply fix** button that drops you into the right surface:

* **Oversized prompt** → links to the offending requests so you can see which prompt template needs trimming.
* **Duplicate requests** → opens the rule editor pre-filled to add a deduplication tag.
* **Model mismatch** → opens `/models/compare` with both models pre-selected, then opens a rule draft.
* **Stuck in retry** → same as model mismatch.

Findings auto-resolve when the underlying behavior disappears from the trailing 7-day window.

## Best practices [#best-practices]


  Check the Optimize page weekly — most findings compound. A $12/month oversized-prompt finding that goes unfixed for a quarter is $36 of wasted spend, and the prompt bloat tends to grow as teams append instructions.


* **Start with the highest-$ finding.** The page ranks by projected savings, so the top card is always the best ROI.
* **Fix model mismatches with rules, not client changes.** A [routing rule](/routeshift/routing) that re-maps `chat` tasks from `o3` to `gpt-4o-mini` fixes every affected key at once — no client deploy needed.
* **Pair with budgets.** After fixing findings, set a [budget](/routeshift/budgets) on the affected keys so the same waste pattern triggers an alert if it recurs.
* **Review after deploys.** New prompt templates or agent deployments are the most common source of new findings. Check Optimize after any significant prompt change.


# Plugins (/routeshift/plugins)



**Plugins** are per-request augmentation steps that run inside the proxy before it dispatches to an upstream provider. They let a single request pull in extra context — live web-search results, extracted PDF content — without the client changing SDKs, wiring a second API, or shipping the enrichment logic itself.



Two plugins are available today:

* [`web`](/routeshift/web-search) — runs a live web search and injects the results into the system prompt as labeled untrusted context.
* [`file-parser`](/routeshift/file-parser) — accepts inline or URL-backed PDF file parts, applies bounded extraction (or fail-closed native PDF passthrough on providers that support it), and forwards the augmented request upstream.

Plugin runs are non-cacheable, so a fresh search or a fresh extraction happens on every request.

## Enabling plugins [#enabling-plugins]

There are three ways to enable a plugin on a request:

* **Model suffix** — append `:online` to the model name (`gpt-4o:online`, `claude-3-5-sonnet:online`) to enable the `web` plugin with default settings.
* **Explicit `plugins` array** — pass one or more plugin objects on the request body to enable `web`, `file-parser`, or both, and to tune their options.
* **Content parts** — the `file-parser` plugin is enabled automatically whenever a request contains a `file` or `input_file` content part; no `plugins` entry is needed.

```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What shipped in the OpenAI DevDay 2026 keynote? Compare against the attached agenda." },
        { "type": "file", "filename": "agenda.pdf", "file": { "file_url": "https://example.com/devday-agenda.pdf" } }
      ]
    }
  ],
  "plugins": [
    { "id": "web", "max_results": 5, "search_prompt": "OpenAI DevDay 2026 keynote announcements" },
    { "id": "file-parser" }
  ]
}
```

The `plugins` array is stripped before the request reaches the upstream provider — providers never see RouteShift-specific fields. The `:online` model suffix is stripped for the same reason.

## Web search [#web-search]

The `web` plugin runs a live search against a configured backend and injects the results into the system prompt as a clearly-delimited untrusted-context block. See [Web search](/routeshift/web-search) for the full options, request/response shape, warning codes, and per-request surcharge.

## File parser [#file-parser]

The `file-parser` plugin turns PDF file parts (base64 inline, or an `https://` URL) into either a bounded text extraction or, on providers with a tested native adapter, a validated native PDF part. It enforces per-file and per-request byte, page, and text-length budgets, and runs URL fetches through an SSRF-safe, DNS-pinned transport.

See [File parser](/routeshift/file-parser) for supported input shapes, budget defaults and environment variables, native-vs-text passthrough rules, and the full list of warning codes.

## Plugin runs, billing, and audit [#plugin-runs-billing-and-audit]

Every plugin execution — whether it ran successfully, degraded to a warning, or errored — writes a sanitized audit row keyed by `(request_id, plugin_id)`. Rows record the plugin id, status (`ok` / `warning` / `error` / `skipped`), latency, cost, and a stable detail code (never a URL, filename, or backend body).

Plugin surcharges are tracked separately from provider model cost, so plugin fees never get silently relabeled as routing spend. Today only the `web` plugin adds a per-invocation surcharge; the `file-parser` plugin does not. Requests that ran a plugin are always marked non-cacheable — the same prompt run twice will pay the surcharge twice. See [Savings and pricing](/routeshift/savings-and-pricing) and [Observability](/routeshift/observability) for how plugin cost and audit rows appear in your usage feed.

Streaming responses can't carry a JSON `warnings` envelope, so the proxy sends the same information as `X-RouteShift-Plugin-Warning` (comma-separated codes) and `X-RouteShift-Plugin-Skip-Reason` (human-readable reasons) headers.

## Using plugins from the SDK [#using-plugins-from-the-sdk]

`@routeshift/sdk` re-exports the wire types (`PluginId`, `PluginSpec`, `PluginWarning`, `PluginWarningResponseMetadata`) so requests are typed end-to-end. Non-streaming responses expose warnings on `res.warnings`; streaming responses expose the header equivalents on `stream.metadata`:

```ts
import { ProxyClient } from "@routeshift/sdk";

const client = new ProxyClient({
  baseUrl: "https://api.routeshift.io",
  apiKey: process.env.ROUTESHIFT_KEY!,
});

// Buffered call — warnings arrive in the response body.
const res = await client.chat({
  model: "gpt-4o",
  plugins: [{ id: "web", max_results: 5 }],
  messages: [{ role: "user", content: "What shipped this week?" }],
});
for (const warning of res.warnings ?? []) {
  console.warn(`${warning.plugin}: ${warning.code}`);
}

// Streaming call — warnings arrive as headers, surfaced through metadata.
const stream = client.chatStream({
  model: "gpt-4o:online",
  plugins: [{ id: "web" }],
  messages: [{ role: "user", content: "Summarize today's filings." }],
});
const { pluginWarning, pluginSkipReason } = await stream.metadata;
if (pluginWarning) console.warn(pluginWarning, pluginSkipReason);
for await (const event of stream) {
  process.stdout.write(event.content ?? "");
}
```

Awaiting `stream.metadata` before iterating is safe — the SDK starts the underlying request once and shares it with the event iterator. If the request fails before headers arrive, `stream.metadata` resolves to an empty object and iterating the stream throws the underlying error.

### Billing [#billing]

Every plugin defaults to **optional**: a backend outage, misconfiguration, or per-file failure attaches a warning to the response and lets the underlying model call proceed. Set `"required": true` on a plugin entry when a degraded answer is worse than a failed request — RouteShift then short-circuits with `502 plugin_required_failed` before dispatching upstream.


# Presets (/routeshift/presets)



A **preset** is a team-scoped, versioned bundle of a canonical model, sampling parameters, an optional system prompt, and provider preferences — addressed by a short slug like `support-bot`. Clients reference the slug at request time; the proxy resolves it to the current preset body before it dispatches upstream.

Every save creates an immutable snapshot in `preset_versions`, so you can diff, audit, or roll back a bad change without stitching state back together from request logs.

## When to use presets [#when-to-use-presets]

Reach for a preset instead of hardcoding request fields when you want to:

* Pin one production configuration — model, temperature, system prompt, provider preferences — behind a stable name that clients don't need to redeploy to change.
* Ship a config change (a smarter model, a lower temperature, a rewritten system prompt) and be able to instantly point back at the previous snapshot if quality regresses.
* Keep an auditable history of who changed which field, and when, without carrying that history in your own database.

Aliases ([Routing & fallbacks](/routeshift/routing)) rewrite the model *name*. Presets rewrite the whole request body. Use aliases for a single-field indirection; use presets when the temperature, system prompt, or provider preferences should travel with the config.

## Anatomy [#anatomy]

| Field            | Type           | Notes                                                                                                                          |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `slug`           | string         | `^[a-z0-9][a-z0-9-]{0,63}$`. Unique per team. Immutable after create.                                                          |
| `version`        | integer        | Monotonic, starts at `1`, increments on every update.                                                                          |
| `model`          | string         | Must be a canonical name from the RouteShift model registry.                                                                   |
| `params`         | object         | Any subset of `temperature`, `max_tokens`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop`. Unknown keys are dropped. |
| `system_prompt`  | string \| null | Optional. Prepended to the request's messages when the preset is resolved.                                                     |
| `provider_prefs` | object         | Provider-preference object (order, allow / deny lists, quantization filters).                                                  |
| `enabled`        | boolean        | Defaults to `true`. Disable a preset to make it fail closed without deleting the version history.                              |

Every preset row is scoped by `team_id`; a slug in team A and the same slug in team B are two independent presets. Cross-team reads return `preset_not_found` — never a distinguishable "wrong team" error.

## Reference a preset from the SDK [#reference-a-preset-from-the-sdk]

`@routeshift/sdk` accepts a `preset` slug on any `chat` or `chatStream` call. Because the preset carries its own canonical model, you can call the proxy without configuring a `defaultModel` on the client and without passing `model` on the request — the proxy resolves both from the preset.

```ts
import { ProxyClient } from "@routeshift/sdk";

const client = new ProxyClient({
  baseUrl: "https://api.routeshift.io",
  apiKey: process.env.ROUTESHIFT_KEY!,
});

// Preset-only call — no model on the client, no model on the request.
const res = await client.chat({
  preset: "support-bot",
  messages: [{ role: "user", content: "How do I reset my password?" }],
});
```

The SDK will not merge its `defaultModel` into a request that carries a `preset`, so a client-side default won't accidentally override the preset's canonical model. Passing `model`, `models`, or a `:online` suffix alongside `preset` still works — those inputs win, exactly as they do on the raw HTTP endpoint.

If you call `chat` with neither a `preset`, a `model`, a `models` array, nor a configured `defaultModel`, the SDK throws before any network call:

```text
model is required when no defaultModel is configured
```

Streaming works the same way:

```ts
const stream = client.chatStream({
  preset: "support-bot",
  messages: [{ role: "user", content: "Draft a triage reply." }],
});

for await (const event of stream) {
  process.stdout.write(event.content ?? "");
}
```

## Manage presets [#manage-presets]

Open **Routing → Presets** in the dashboard, or drive the API directly. Only workspace admins can create, update, or delete presets. Any team member can read them.

### Create [#create]

```http
POST /api/presets
Content-Type: application/json

{
  "slug": "support-bot",
  "model": "gpt-4o",
  "params": { "temperature": 0.2, "max_tokens": 1024 },
  "system_prompt": "You are a support agent for Acme…",
  "provider_prefs": { "order": ["openai", "azure"] },
  "enabled": true
}
```

Returns `{ "id": "preset_…", "slug": "support-bot", "version": 1, "proxy_cache_invalidated": true }` with `201`. On slug collision the API returns `409 preset_slug_taken`. Invalid slugs return `400 invalid_preset_slug`; unknown models return `400 invalid_preset_model`.

Every accepted write (`POST`, `PUT`, disable, delete) also invalidates the proxy's preset cache so the change takes effect on the next request. The response reports the outcome of that step explicitly:

* On success: `"proxy_cache_invalidated": true`.
* On failure: `"proxy_cache_invalidated": false`, `"proxy_cache_error": "proxy_cache_invalidation_failed"`, and `"cache_ttl_seconds"` — the database write still committed, but the proxy may keep serving the previous preset until the TTL elapses.

### Update [#update]

```http
PUT /api/presets/support-bot
Content-Type: application/json

{
  "model": "gpt-4o",
  "params": { "temperature": 0.3, "max_tokens": 1024 },
  "system_prompt": "You are a support agent for Acme…",
  "provider_prefs": { "order": ["openai", "azure"] }
}
```

`PUT` is a **full-body replace**. `model`, `params`, `system_prompt`, and `provider_prefs` are all required — omit any and the request fails with `400 full_preset_body_required`. `enabled` is optional and preserves its current value when omitted.

Every accepted `PUT` bumps `version` by one and appends a `preset_versions` row. The response is `{ "slug": "support-bot", "version": 2, "proxy_cache_invalidated": true }` — see [Proxy cache invalidation](#proxy-cache-invalidation) for the failure shape.

### Delete or disable [#delete-or-disable]

```http
DELETE /api/presets/support-bot            # remove the row and mark it not-found
DELETE /api/presets/support-bot?disable=true   # keep history, set enabled=false
```

Use `?disable=true` when you want the slug to fail closed but keep the version history discoverable. A hard `DELETE` removes the `presets` row (`preset_versions` rows persist for audit).

Both variants return `{ "ok": true, "disabled": , "proxy_cache_invalidated": true }` on success. If the proxy invalidation call fails, the database write still commits and the response reports [proxy cache invalidation](#proxy-cache-invalidation) explicitly.

## Proxy cache invalidation [#proxy-cache-invalidation]

After a successful create, publish, delete, or disable, the dashboard tells the proxy to drop its cached copy of the preset so the next request resolves the new body immediately. Every successful mutation response includes an explicit status for that side effect:

| Field                     | Type    | When present                                                                                                                                                                     |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proxy_cache_invalidated` | boolean | Always. `true` when the proxy accepted the invalidation, `false` on any failure.                                                                                                 |
| `proxy_cache_error`       | string  | Only when `proxy_cache_invalidated` is `false`. Fixed value `proxy_cache_invalidation_failed`.                                                                                   |
| `cache_ttl_seconds`       | integer | Only when `proxy_cache_invalidated` is `false`. Currently `60` — the upper bound on how long stale routing can persist before the proxy TTL expires the cached entry on its own. |

The database write is **committed** before the invalidation call runs, so a `proxy_cache_invalidated: false` response still means the preset was saved. The proxy may serve the previous version for up to `cache_ttl_seconds` before it re-reads from the database.

```json
{
  "slug": "support-bot",
  "version": 2,
  "proxy_cache_invalidated": false,
  "proxy_cache_error": "proxy_cache_invalidation_failed",
  "cache_ttl_seconds": 60
}
```

### How to handle it [#how-to-handle-it]

* **Non-blocking clients** (dashboards, background jobs): treat the response as a success — the preset is saved, and the proxy will pick it up within `cache_ttl_seconds`.
* **Change-control flows** where new traffic must land on the new version immediately: surface `proxy_cache_error` to the operator and retry the same request (idempotent for `PUT`, `DELETE`, and `DELETE?disable=true`) until you see `proxy_cache_invalidated: true`, or wait out `cache_ttl_seconds` before declaring the rollout done.
* **`POST` retries**: the create already committed, so retrying with the same slug returns `409 preset_slug_taken`. To force invalidation after a failed `POST`, issue a `PUT` with the same body — it bumps the version and re-runs invalidation.

The proxy admin endpoint the dashboard calls is documented in [Admin API](/routeshift/api/admin); a `proxy_admin_secret_not_configured` response (`500`) means the dashboard is misconfigured and no mutations will invalidate the cache until the secret is set.

## Version history [#version-history]

Every accepted create and update writes an immutable snapshot to `preset_versions`. Snapshots are keyed by `(team_id, preset_id, version)` and carry the full body (`model`, `params`, `system_prompt`, `provider_prefs`) plus `created_by` and `created_at`.


  Preset version history is scoped strictly to the caller's team. A request for `GET /api/presets/{slug}/versions` from a team that doesn't own `{slug}` returns the same `404 preset_not_found` response as a truly missing preset — teams can't probe the existence of another team's presets.


### List snapshots [#list-snapshots]

```http
GET /api/presets/{slug}/versions
```

Returns every snapshot for the slug, newest first:

```json
{
  "versions": [
    {
      "version": 3,
      "model": "gpt-4o",
      "params": { "temperature": 0.3, "max_tokens": 1024 },
      "system_prompt": "You are a support agent for Acme…",
      "provider_prefs": { "order": ["openai", "azure"] },
      "created_by": "user_01H…",
      "created_at": "2026-07-09T18:42:11.204Z"
    },
    {
      "version": 2,
      "model": "gpt-4o",
      "params": { "temperature": 0.2, "max_tokens": 1024 },
      "system_prompt": "You are a support agent for Acme…",
      "provider_prefs": { "order": ["openai"] },
      "created_by": "user_01H…",
      "created_at": "2026-06-30T14:10:03.612Z"
    }
  ]
}
```

### Read one snapshot [#read-one-snapshot]

```http
GET /api/presets/{slug}/versions/{version}
```

`{version}` must be a positive base-10 integer within the PostgreSQL 32-bit `integer` range (max `2147483647`). Leading zeros, negative values, decimals, and values outside the range return `400 invalid_preset_version` before any database lookup.

```json
{
  "version": {
    "version": 2,
    "model": "gpt-4o",
    "params": { "temperature": 0.2, "max_tokens": 1024 },
    "system_prompt": "You are a support agent for Acme…",
    "provider_prefs": { "order": ["openai"] },
    "created_by": "user_01H…",
    "created_at": "2026-06-30T14:10:03.612Z"
  }
}
```

### Roll back to a previous version [#roll-back-to-a-previous-version]

There's no `POST /rollback` shortcut — read the snapshot you want and replay it as a `PUT`:

```bash
# Fetch version 2, strip the audit fields, replay as an update.
curl -s https://app.routeshift.io/api/presets/support-bot/versions/2 \
  -H "Authorization: Bearer $ROUTESHIFT_SESSION" \
  | jq '.version | { model, params, system_prompt, provider_prefs }' \
  | curl -s -X PUT https://app.routeshift.io/api/presets/support-bot \
      -H "Authorization: Bearer $ROUTESHIFT_SESSION" \
      -H "Content-Type: application/json" \
      --data-binary @-
```

The result is a new snapshot (say `version = 4`) whose body is identical to version 2. History stays linear and append-only, which keeps the audit story simple — no version is ever mutated or removed.

## Errors [#errors]

| Response                    | Status | When                                                                                            |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `invalid_preset_slug`       | 400    | Slug doesn't match `^[a-z0-9][a-z0-9-]{0,63}$`.                                                 |
| `invalid_preset_model`      | 400    | Model is not in the canonical model registry.                                                   |
| `invalid_preset_params`     | 400    | `params` is not a JSON object.                                                                  |
| `invalid_preset_version`    | 400    | Version path segment is not a positive integer within `int4` range.                             |
| `full_preset_body_required` | 400    | `PUT` omitted one of `params`, `system_prompt`, or `provider_prefs`.                            |
| `preset_not_found`          | 404    | Slug doesn't exist in the caller's team — including when it exists in another team.             |
| `preset_slug_taken`         | 409    | `POST` with a slug already used by the team.                                                    |
| `Admin role required`       | 403    | Non-admin attempted a write. Reads only require team membership.                                |
| Demo write blocked          | 403    | Demo mode is read-only. Preset writes are blocked; reads still work against the demo workspace. |

## Demo mode [#demo-mode]

Preset **reads** (list, detail, version history) transparently substitute the demo team for the caller's team when demo mode is active — you see the demo workspace's presets and version history, exactly as they'd render in production. Preset **writes** (`POST`, `PUT`, `DELETE`) are blocked with `403` so a demo session can't mutate the real workspace.


# Supported providers (/routeshift/providers)



RouteShift normalizes twelve LLM providers behind a single OpenAI-compatible API. You bring the credentials; the proxy handles auth shape, header conventions, and response decoding.



## Catalog [#catalog]

| Provider                     | Auth shape              | Notes                                                                         |
| ---------------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| **OpenAI**                   | `Authorization: Bearer` | Direct passthrough.                                                           |
| **Anthropic**                | `x-api-key`             | Anthropic Messages API.                                                       |
| **Google**                   | API key                 | Gemini family. Structured output and rich tool schemas supported — see below. |
| **AWS Bedrock**              | SigV4                   | Configure `access_key_id` + `region` in the provider key's `metadata` jsonb.  |
| **Azure OpenAI**             | API key                 | Configure `resource_name` + `api_version` in `metadata`.                      |
| **Together**                 | `Authorization: Bearer` | OpenAI-compatible.                                                            |
| **Groq**                     | `Authorization: Bearer` | OpenAI-compatible, very low latency.                                          |
| **Z.ai (Zhipu GLM)**         | `Authorization: Bearer` | OpenAI-compatible.                                                            |
| **Xiaomi MiMo**              | API key                 | Custom auth header, OpenAI-compatible body.                                   |
| **MiniMax**                  | `x-api-key` or `Bearer` | Anthropic-compatible.                                                         |
| **Moonshot (Kimi)**          | `x-api-key` or `Bearer` | Anthropic-compatible. Current model IDs: `kimi-k2.6`, `kimi-k2.7-code`.       |
| **Alibaba Qwen (DashScope)** | `Authorization: Bearer` | OpenAI-compatible.                                                            |

## Google Gemini: structured output and tool schemas [#google-gemini-structured-output-and-tool-schemas]

Gemini requests routed through RouteShift accept the full OpenAI-compatible `response_format` and `tools` shapes — you don't need to hand-craft Gemini-specific request bodies. The proxy translates the client JSON Schema onto Gemini's JSON-Schema-native `generateContent` fields:

* `response_format: { type: 'json_object' }` and `response_format: { type: 'json_schema', json_schema: { schema } }` are mapped to `generationConfig.responseMimeType` (`application/json`) plus `generationConfig.responseJsonSchema`.
* `tools[].function.parameters` is sent as `functionDeclarations[].parametersJsonSchema` — the lossless JSON Schema field — instead of Gemini's older OpenAPI-subset `parameters`.

The practical upshot: schemas that use `additionalProperties`, `$ref`, `oneOf`, and other JSON Schema features that Gemini's OpenAPI subset rejects now validate and run. Send the same request you'd send to OpenAI:

```json
{
  "model": "gemini-2.5-pro",
  "messages": [{ "role": "user", "content": "Return a user object." }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "user",
      "schema": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "email": { "type": "string" } },
        "required": ["id", "email"],
        "additionalProperties": false
      }
    }
  }
}
```

Applies to the Gemini Developer API surface (`generativelanguage.googleapis.com/v1beta`).

## Moonshot (Kimi) model IDs [#moonshot-kimi-model-ids]

The Moonshot line-up on `platform.kimi.ai` moved off `Kimi-K2-Thinking`. RouteShift's registry now tracks the two current direct-API models — send these IDs in the `model` field:

| Model ID         | Context        | Input / M | Cache-hit / M | Output / M |
| ---------------- | -------------- | --------- | ------------- | ---------- |
| `kimi-k2.6`      | 262,144 tokens | $0.95     | $0.16         | $4.00      |
| `kimi-k2.7-code` | 262,144 tokens | $0.95     | $0.19         | $4.00      |

Pricing tracks the official Moonshot pages; RouteShift's cost accounting and provider key-test both use these IDs. If you have code pinned to `Kimi-K2-Thinking`, update it — the old ID is deprecated upstream.

## Provider keys [#provider-keys]

A **provider key** is the upstream credential. Add one at **Settings → Providers → Add credential**. RouteShift encrypts the secret with `PROVIDER_KEY_SECRET` (AES-GCM at rest) and never returns it after save.

For providers that need extra non-secret config (Bedrock and Azure), the form exposes structured fields that are stored in a `metadata jsonb` column. Edit them anytime without re-entering the secret.

## Multiple keys per provider [#multiple-keys-per-provider]

You can attach **N labeled provider keys** for the same provider — one per region, one per OpenAI org, one per Bedrock account. Each key is an independent target for [load balancing](/routeshift/routing#load-balancing-across-n-provider-keys), with its own RPM/TPM, weight, and cooldown state.

Examples:

* Two Bedrock credentials in `us-east-1` and `us-west-2` for failover.
* A "paid" OpenAI key plus a "trial" key for cost arbitrage.
* Multiple Azure deployments fronting the same model for capacity scaling.

## Adding a new provider [#adding-a-new-provider]

The provider abstraction lives in `apps/proxy/src/providers/` — see `OpenAICompatProvider` and `AnthropicCompatProvider` for the two base shapes, and `BedrockProvider` / `AzureProvider` for examples that need richer config. Most regional providers are 50–150 LOC of glue.

If you'd like a provider added that isn't in the catalog above, open an issue at [github.com/smynkr/RouteShift](https://github.com/smynkr/RouteShift) or email [support@routeshift.io](mailto:support@routeshift.io).


# Routing & fallbacks (/routeshift/routing)



Every request that hits RouteShift gets matched against a **routing rule chain** before it leaves the proxy. Rules can rewrite the model, swap providers, attach metadata, or short-circuit with a static response — all without your client knowing.



## Rules [#rules]

Open **Routing → Rules** to create a rule. A rule has:

* **Match** — match on virtual key, model name, message content regex, message size, system-prompt size, or metadata.
* **Action** — `route` to a specific model, `block` with a status code, or `tag` for downstream analytics.
* **Priority** — lower numbers win. Rules are evaluated top-to-bottom in priority order.
* **Conditions** — optional time-of-day, environment, or per-key gates.

Rules are versioned; every save records a diff in the audit log so you can roll back a bad change.

## Model aliases [#model-aliases]

A **model alias** is a per-team canonical name that resolves to a real upstream model. Use aliases to:

* Standardize on a single name across providers (`smart` → `gpt-4o`, `cheap` → `gpt-4o-mini`, `claude` → `claude-3-5-sonnet-20241022`).
* Pin a public name to a specific version while you migrate.
* Swap models for a whole team without touching any client code.

Aliases live at **Routing → Aliases**. When the resolver changes, the proxy invalidates its cache via `/admin/model-aliases/invalidate`, so updates take effect on the next request.

## Load balancing across N provider keys [#load-balancing-across-n-provider-keys]

If you have multiple credentials for the same provider — multiple OpenAI orgs, multiple Bedrock regions, multiple Azure deployments — RouteShift can balance traffic across them. Configure the strategy at **Settings → Providers → … → Load balancing**:

| Strategy                 | When to use                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Weighted round-robin** | Default. Each key gets traffic proportional to its weight. Useful for cost arbitrage between paid and free tiers. |
| **Latency-based**        | Routes to the fastest p50 over the last 5 minutes. Good for multi-region deployments.                             |
| **Least-busy**           | Routes to the key with the lowest in-flight request count. Useful when keys have very different RPM caps.         |

Keys also have **automatic cooldowns**: a sustained burst of `5xx` or `429` from upstream takes the key out of rotation for a configurable window. The dashboard shows cooldown state in real time.

## Retry budget and cost ceiling [#retry-budget-and-cost-ceiling]

Fallbacks aren't free — a chain of three retries against three different providers can cost 3× the original request. Every rule supports two caps:

* **Retry budget** — max attempts across the chain. Defaults to 3.
* **Per-request cost ceiling** — max USD a single client request can spend across all attempts. When the ceiling is hit, the next attempt is skipped and the last error is returned.

Both caps are enforced server-side, so a misconfigured rule chain can't produce a runaway bill.

## Provider-side rate-limit awareness [#provider-side-rate-limit-awareness]

When an upstream provider returns a `429` or a `Retry-After` header, RouteShift honors it: the offending credential is parked until the cooldown expires, and any in-flight retry is rerouted to a different key (or the next model in the rule chain). The cooldown is per-credential, so noisy neighbors don't take down a whole provider.


# Savings & pricing (/routeshift/savings-and-pricing)



RouteShift is BYOK by default: you bring provider keys, the proxy never resells inference. The only thing RouteShift charges for is the routing layer itself — and the charge is **3% of the measured savings**, not a flat platform fee. If you don't save money, you don't pay.



## Where prices come from [#where-prices-come-from]

Token prices are pulled from the [LiteLLM model\_prices\_and\_context\_window.json](https://github.com/BerriAI/litellm) catalog — the de-facto open-source registry of every public LLM's pricing. RouteShift syncs the catalog weekly via a GitHub Action that opens a PR if the catalog has changed; merge the PR and the new prices ship on the next deploy.

This means:

* New model launches show up in RouteShift's pricing within a week without any manual data entry.
* Provider price drops propagate the same way.
* The proxy and the dashboard read from the same generated TypeScript file (`packages/shared/src/litellm-pricing.generated.ts`), so analytics and routing decisions always use the same numbers.

If a model isn't in the catalog (e.g. a private deployment), RouteShift falls back to an explicit per-deployment price you set in **Settings → Providers**.

## How savings are measured [#how-savings-are-measured]

For every request, RouteShift records:

* **Actual cost** — what the request actually cost on the model it was routed to.
* **Baseline cost** — what the same request would have cost on your declared baseline model. The baseline defaults to the model the client originally asked for; teams can override it (e.g. "everyone was on `gpt-4o` before — measure against that").

**Savings = baseline cost − actual cost**. RouteShift floors negative savings (a "savings" that's actually more expensive than baseline) to zero before billing — you only pay on net wins.

### Choosing a baseline [#choosing-a-baseline]

The baseline model is the "what would we have paid without RouteShift" reference. By default it's the model the client originally requested — so if your code asks for `gpt-4o` and RouteShift routes it to `gpt-4o-mini` at lower cost, the savings are measured against `gpt-4o` pricing.

You can override the baseline per team at **Settings → Teams → … → Baseline model**. Common patterns:

| Scenario                               | Baseline choice        | Why                                             |
| -------------------------------------- | ---------------------- | ----------------------------------------------- |
| Migrating from a single frontier model | The old frontier model | Measures the total routing benefit              |
| Multi-model shop                       | Per-team baseline      | Each team measures against its own status quo   |
| Cost-center reporting                  | Cheapest viable model  | Shows the premium paid for quality, not savings |

## The 3% savings-share [#the-3-savings-share]

Once a month, RouteShift sums total savings for the workspace and bills 3% of it through Stripe. The line item shows up in your invoice with a link to the underlying calculation.

* **Generous free tier** — workspaces under a configurable monthly threshold pay nothing.
* **No platform fee** — there is no monthly base charge, no seat charge, no minimum.
* **No markup on tokens** — the 3% comes out of savings RouteShift produced, not on top of provider pricing.
* **Transparent ledger** — every billed dollar links to the request logs that produced it.

### Reading the savings dashboard [#reading-the-savings-dashboard]

The **Billing → Savings** page shows:

* **Trailing 30-day savings** — total USD saved across all keys, with a daily sparkline.
* **Per-model breakdown** — which model swaps produced the most savings (e.g. `gpt-4o → gpt-4o-mini` saved $X, `claude-3-5-sonnet → claude-3-5-haiku` saved $Y).
* **Per-key breakdown** — which teams or API keys are driving the savings.
* **Projected monthly bill** — 3% of trailing savings, updated daily.

## Billing FAQ [#billing-faq]


  
    Negative savings are floored to zero. You never pay extra because of a routing decision. The request still completes normally — the savings ledger simply doesn't count it as a win.
  

  
    Yes. Every invoice line item links to the request logs that produced it. You can download the full request-level CSV from **Billing → Export** and verify the savings calculation independently.
  

  
    Weekly, via the LiteLLM catalog sync. Provider price drops propagate automatically. New models appear within a week of their LiteLLM catalog entry.
  

  
    No. RouteShift is month-to-month with no minimum spend. If your savings are below the free-tier threshold, you pay nothing.
  



  Pricing details and the savings calculation are also covered on the [routeshift.io](https://routeshift.io) marketing site.



# SSO device flow (/routeshift/sso-device-flow)



The SSO device flow lets an employee at a Google Workspace or Okta org run a CLI command, approve it in their browser via a real IdP sign-in, and receive a short-lived `sk-proxy-…` key scoped to their identity. It's a full [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) OAuth 2.0 Device Authorization Grant implementation — no admin has to manually mint or share credentials.

## When to use it [#when-to-use-it]

Use SSO device-flow keys for:

* **Interactive CLI tools** — anywhere a developer runs a local command that needs a RouteShift key.
* **Notebooks and one-off scripts** — short-lived credentials that auto-expire.
* **Onboarding** — new hires get a working key the moment they can sign in to your IdP, with no admin ticket.

Stick with regular [virtual keys](/routeshift/keys) for:

* **Production services and CI** — long-lived, machine-owned credentials with per-key budgets and model allowlists.
* **Shared agents** — keys that outlive any one employee.

## How the flow works [#how-the-flow-works]




  
    ### Employee runs the CLI [#employee-runs-the-cli]

    Their local tool calls `POST /oauth/device/code` with the employee's email. RouteShift looks up the team by email domain (home-realm discovery) and returns a `device_code`, an 8-character `user_code`, and a `verification_uri`.
  

  
    ### Employee approves in the browser [#employee-approves-in-the-browser]

    The CLI prints the code and opens `https://api.routeshift.io/oauth/device/verify`. The employee signs in to Google Workspace or Okta, sees the code they were shown, and clicks **Approve**.
  

  
    ### RouteShift verifies the identity [#routeshift-verifies-the-identity]

    The IdP redirects back to `/oauth/device/callback` with an authorization code. RouteShift exchanges it for an ID token, validates the issuer, audience, nonce, and email domain, then marks the authorization approved.
  

  
    ### CLI receives a key [#cli-receives-a-key]

    The CLI has been polling `POST /oauth/device/token` with the `device_code`. Once approved, it receives a fresh `sk-proxy-…` token valid for 8 hours.
  


Keys minted this way are stamped with `metadata.issued_via = "sso_device_flow"` and `metadata.email = ""`. Only one live SSO key is allowed per `(team, email)` pair — a second flow for the same identity replaces the previous key.

## Key properties [#key-properties]

| Property       | Value                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **TTL**        | 8 hours (fixed)                                                                                                                           |
| **Scope**      | Full workspace API access — same as any virtual key. Combine with team-level budgets and rate limits for guardrails.                      |
| **Uniqueness** | One live SSO key per `(team, email)`. Re-running the flow revokes the previous key.                                                       |
| **Audit**      | Every issuance writes an `sso_issued` event to the [key audit log](/routeshift/keys#key-lifecycle), including the verified email and IdP. |
| **Revocation** | Manual via **Keys → … → Revoke**, or automatic when the sweeper clears the row after `expires_at`.                                        |


  The 8-hour TTL is a deliberate defense against leaked keys — even if the token ends up in a repo or a chat log, its blast radius closes overnight.


## Configuring an IdP connection [#configuring-an-idp-connection]

Every team that wants SSO device flow needs one `idp_config` row per login domain. Provision it via the [admin API](/routeshift/api/admin#sso-device-flow):

Set a local shell variable from your approved secret manager. Its value must be the deployment's unrestricted operator credential (`ADMIN_SECRET`), not a scoped admin token; scoped tokens cannot call this mutation.

```bash
export ROUTESHIFT_ADMIN_TOKEN=""

curl -X POST https://api.routeshift.io/admin/idp-configs \
  -H "Authorization: Bearer ${ROUTESHIFT_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_…",
    "provider": "okta",
    "login_domain": "acme.com",
    "issuer": "https://acme.okta.com",
    "client_id": "0oab…",
    "client_secret": "…"
  }'
```

Requirements:

* **`provider`** — `google_workspace` or `okta`.
* **`login_domain`** — the email domain employees sign in with (e.g. `acme.com`). A domain belongs to exactly one team; conflicts return `409`.
* **`issuer`** — the OIDC issuer URL. RouteShift fetches its discovery document at create time to validate reachability and the JWKS endpoint. Do not include a trailing slash — the issuer is compared byte-for-byte against the `iss` claim during token verification.
* **`client_id` / `client_secret`** — the OAuth app you registered in the IdP console. The secret is encrypted at rest with `PROVIDER_KEY_SECRET`.
* **Redirect URI** — register `${SSO_CALLBACK_BASE_URL}/oauth/device/callback` in the IdP app console. This must match the environment variable exactly.


  The IdP-side redirect URI must exactly match `SSO_CALLBACK_BASE_URL` configured on the proxy. A mismatch causes the browser leg to fail with an opaque IdP error before RouteShift ever sees the callback.


## CLI example [#cli-example]

A minimal client that walks the flow:

```ts
async function ssoLogin(email: string): Promise {
  // 1. Request a device code
  const start = await fetch("https://api.routeshift.io/oauth/device/code", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email }),
  }).then((r) => r.json());

  console.log(`Open ${start.verification_uri_complete}`);
  console.log(`Or visit ${start.verification_uri} and enter code: ${start.user_code}`);

  // 2. Poll for the key
  while (true) {
    await new Promise((r) => setTimeout(r, start.interval * 1000));
    const res = await fetch("https://api.routeshift.io/oauth/device/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        device_code: start.device_code,
        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
      }),
    });
    const body = await res.json();
    if (res.ok) return body.access_token; // sk-proxy-…
    if (body.error === "authorization_pending" || body.error === "slow_down") continue;
    throw new Error(body.error_description ?? body.error);
  }
}
```

The device-code endpoint returns:

```json
{
  "device_code": "…",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://api.routeshift.io/oauth/device/verify",
  "verification_uri_complete": "https://api.routeshift.io/oauth/device/verify?user_code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}
```

The token endpoint returns standard RFC 8628 errors:

| Error                   | Meaning                                                       |
| ----------------------- | ------------------------------------------------------------- |
| `authorization_pending` | Keep polling — the user hasn't approved yet.                  |
| `slow_down`             | You're polling too fast. Increase the interval by 5 seconds.  |
| `expired_token`         | The `device_code` expired (10 minutes). Start over.           |
| `access_denied`         | The user clicked **Deny** on the verify page.                 |
| `invalid_grant`         | The `device_code` is unknown, already consumed, or malformed. |

## Rollout gate [#rollout-gate]

The device flow is disabled by default. To enable it on a deployment:

1. Set `SSO_DEVICE_FLOW_ENABLED=true` on `apps/proxy`.
2. Set `SSO_CALLBACK_BASE_URL` to the public HTTPS origin of the proxy (must match the redirect URI you register in each IdP).
3. Provision at least one `idp_config` via the admin API.


  `SSO_DEVICE_FLOW_ENABLED` is a **per-team onboarding gate**, not a global kill switch. Once a team has an `idp_configs` row, flipping the flag off does not stop that team's employees from logging in. To disable a specific team, delete their `idp_configs` row via `DELETE /admin/idp-configs/{id}?team_id=…`.


## Audit [#audit]

Every SSO-issued key writes an `sso_issued` event to `api_key_audit_events` with the verified email, IdP config ID, and issuance timestamp. Filter for these in the audit log to see which employees are actively using the flow.

Revocation, rotation, and expiry follow the same [key lifecycle](/routeshift/keys#key-lifecycle) as any other virtual key.


# Team & access (/routeshift/team)



A RouteShift workspace can have any number of members. Roles control what each member can see and do.



## Roles [#roles]

| Role       | Capabilities                                                                                                                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**  | Everything Admin can do, plus invitations, member role changes/removals, and workspace deletion. One owner per workspace.                                 |
| **Admin**  | Read and manage keys, providers, routing rules, and billing. Admins can list pending invitations, but cannot create invitations or change/remove members. |
| **Member** | Read-only on dashboards and request logs. Cannot mint keys, edit rules, or add providers.                                                                 |

### Role comparison [#role-comparison]

| Action                      | Owner | Admin | Member |
| --------------------------- | :---: | :---: | :----: |
| View dashboards and logs    |   ✓   |   ✓   |    ✓   |
| Mint / edit / revoke keys   |   ✓   |   ✓   |    —   |
| Add / edit providers        |   ✓   |   ✓   |    —   |
| Create / edit routing rules |   ✓   |   ✓   |    —   |
| View billing and invoices   |   ✓   |   ✓   |    —   |
| Invite members              |   ✓   |   —   |    —   |
| Change member roles         |   ✓   |   —   |    —   |
| Remove members              |   ✓   |   —   |    —   |
| Delete workspace            |   ✓   |   —   |    —   |

## Inviting members [#inviting-members]

Only the workspace owner can create invitations. Open **Settings → Team → Invite**, enter the email, and choose `member` or `admin`. RouteShift returns a magic-link URL that expires in 7 days for the owner to share. Owners and admins can list pending invitations; invitation creation, role changes, and removals are owner-only operations.

Invites are tied to email — once accepted, the member signs in via the same auth flow as the owner.

Invitations are stored against a normalized (trimmed, lowercase) email and duplicate member or pending-invite requests return `409`. Accepting an invitation adds the user to the team; role changes are limited to `member` and `admin`, and an owner cannot change or remove another owner.

### Invitation lifecycle [#invitation-lifecycle]


  
    ### Owner creates invitation [#owner-creates-invitation]

    The owner enters an email and selects a role (`member` or `admin`). RouteShift generates a magic-link URL valid for 7 days.
  

  
    ### Owner shares the link [#owner-shares-the-link]

    The magic-link URL is shared out-of-band (email, Slack, etc.). RouteShift does not send the invitation email directly — the owner controls delivery.
  

  
    ### Recipient accepts [#recipient-accepts]

    Clicking the link creates the account (or links an existing one) and adds the member to the workspace with the specified role. The invitation is consumed and cannot be reused.
  

  
    ### Audit trail [#audit-trail]

    The invitation, acceptance, and any subsequent role changes are recorded in the workspace audit log.
  


## Audit log [#audit-log]

Every membership change (invited, accepted, role changed, removed) writes to the workspace audit log alongside key and routing-rule changes. Filter by `type=membership` to see only access events.

## Single sign-on [#single-sign-on]

For per-employee, short-lived API keys backed by real IdP authentication, use the [SSO device flow](/routeshift/sso-device-flow) — CLI-driven login against Google Workspace or Okta, no admin involvement.

Dashboard SSO via SAML or OIDC is on the roadmap; reach out to [support@routeshift.io](mailto:support@routeshift.io) if you need it.


# Web search (/routeshift/web-search)



The **web search plugin** lets any chat completion pull in current web results before the model responds. You opt in per request; RouteShift queries a search backend, formats the top results as a clearly labeled context block, appends it to the system prompt, and forwards the request to the upstream provider. The model sees titles, URLs, and snippets — but never sees a raw `plugins` field.



Web search runs entirely proxy-side, so you don't need to change providers or wire up your own search integration. Any model you can call through RouteShift can be augmented this way.

## When to use it [#when-to-use-it]

Turn on web search when the answer depends on information that may be newer than the model's training cutoff — release notes, current prices, breaking news, regulatory changes, or anything else that's genuinely time-sensitive. Skip it for evergreen prompts (code generation, summarization of user-supplied text, math). Each augmented request adds a search-backend round trip and a per-request surcharge, and cache reuse is disabled for the augmented turn.

## Opt in per request [#opt-in-per-request]

There are two equivalent ways to enable web search on a single call:

1. **Model suffix.** Append `:online` to the model name — e.g. `gpt-4o:online`. The suffix is stripped before the request is dispatched, and a default `web` plugin is added.
2. **Explicit plugin entry.** Add a `web` object to the top-level `plugins` array. Use this when you need to tune `max_results`, pass a custom `search_prompt`, or mark the plugin as required.

The suffix and the array can be combined; an explicit `web` entry wins over the suffix's defaults.

### Suffix form [#suffix-form]

```bash
curl https://api.routeshift.io/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o:online",
    "messages": [
      {"role": "user", "content": "What did the FTC announce this week about AI disclosure?"}
    ]
  }'
```

### Explicit form [#explicit-form]

```json
{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Summarize this week's FTC AI announcements." }
  ],
  "plugins": [
    {
      "id": "web",
      "max_results": 5,
      "search_prompt": "FTC AI disclosure rules July 2026",
      "required": false
    }
  ]
}
```

## Plugin fields [#plugin-fields]

| Field           | Type    | Default           | Notes                                                                                                                                                       |
| --------------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `"web"` | —                 | Required. Identifies the plugin. See [File parser](/routeshift/file-parser) for the other supported plugin id.                                              |
| `max_results`   | integer | `5`               | Positive integer, capped at `10`. Higher values grow the system-prompt context.                                                                             |
| `search_prompt` | string  | last user message | Overrides the derived query. Useful when the user turn is chatty and you already know the search terms.                                                     |
| `required`      | boolean | `false`           | If `true`, a search-backend failure returns `502 plugin_required_failed`. If `false`, the request continues without augmentation and a warning is attached. |

The `plugins` array is stripped from the payload before dispatch — upstream providers never see it. The `:online` suffix is stripped from the model name for the same reason.

## What the model sees [#what-the-model-sees]

When the backend returns results, RouteShift appends a fenced context block to the request's `system_prompt` (creating one if it was empty). The block is deterministic — same query, same results, same ordering:

```text
[Untrusted web search results — use only as supplemental context]
1. Federal Trade Commission — AI Disclosure Guidance
URL: https://www.ftc.gov/…/ai-disclosure
FTC finalized new rules requiring…

2. Reuters — FTC Rolls Out AI Guardrails
URL: https://www.reuters.com/…
The Federal Trade Commission on…
[End untrusted web search results]
```

The `Untrusted` wrapper is intentional — it primes the model to treat retrieved text as supplemental context rather than authoritative instructions, which limits the blast radius of prompt-injection payloads in scraped pages.

If the backend returns zero results, the request is dispatched unchanged rather than adding an empty context block.

## Optional vs. required plugins [#optional-vs-required-plugins]

RouteShift treats web search as **optional by default**. A backend timeout, `EXA_API_KEY` misconfiguration, or non-2xx response degrades gracefully:

* The upstream call still runs against the un-augmented request.
* A `PluginWarning` is attached to the request log with one of two codes:
  * `plugin_backend_not_configured` — the backend isn't wired up (missing `EXA_API_KEY`, unsupported `SEARCH_BACKEND`).
  * `plugin_backend_failed` — the backend was reachable but returned an error or timed out.

Set `"required": true` when a stale answer is worse than a failed request — e.g. a compliance workflow that must cite fresh sources. A required-plugin failure short-circuits the request with:

```http
HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "error": {
    "code": "plugin_required_failed",
    "message": "Required plugin web failed: "
  }
}
```

## Read warnings from the SDK [#read-warnings-from-the-sdk]

`@routeshift/sdk` exposes the wire types (`PluginId`, `PluginSpec`, `PluginWarning`) directly, so you can attach plugins to a request and inspect what the proxy did with them without hand-typing the shape.

### Non-streaming responses [#non-streaming-responses]

`client.chat(...)` returns a `ChatCompletionResponse` whose `warnings` array carries every optional-plugin degradation the proxy reported. The array is absent when nothing was skipped.

```ts
import { ProxyClient, type PluginWarning } from "@routeshift/sdk";

const client = new ProxyClient({
  baseUrl: "https://api.routeshift.io",
  apiKey: process.env.ROUTESHIFT_KEY!,
});

const res = await client.chat({
  model: "gpt-4o",
  plugins: [{ id: "web", max_results: 5, search_prompt: "current pricing" }],
  messages: [{ role: "user", content: "What did OpenAI announce this week?" }],
});

for (const warning of res.warnings ?? []) {
  console.warn(`${warning.plugin}: ${warning.code} — ${warning.message}`);
}
```

### Streaming responses [#streaming-responses]

SSE bodies don't carry the JSON `warnings` envelope, so the proxy reports the same information through response headers. `client.chatStream(...)` returns a `ChatCompletionStream` that exposes a `metadata` promise; it resolves to `ChatCompletionStreamMetadata` with the raw header values.

```ts
const stream = client.chatStream({
  model: "gpt-4o:online",
  plugins: [{ id: "web", required: false }],
  messages: [{ role: "user", content: "Summarize this week's SEC filings." }],
});

// Awaiting metadata before iteration is safe — the SDK starts the underlying
// request once and shares it with the event iterator.
const meta = await stream.metadata;
if (meta.pluginWarning) {
  console.warn("plugin warnings:", meta.pluginWarning.split(","));
  console.warn("reasons:", meta.pluginSkipReason);
}

for await (const event of stream) {
  process.stdout.write(event.content ?? "");
}
```

| Field                    | Source header                     | Shape                                                                                        |
| ------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------- |
| `pluginWarning`          | `X-RouteShift-Plugin-Warning`     | Comma-separated warning codes (`plugin_backend_not_configured`, `plugin_backend_failed`, …). |
| `pluginSkipReason`       | `X-RouteShift-Plugin-Skip-Reason` | Human-readable reason string; multiple reasons are joined with `\|`.                         |
| `_routeshift_request_id` | `x-routeshift-request-id`         | The same request id attached to non-streaming responses.                                     |

If the request fails before headers arrive (e.g. the proxy returns `503`), `stream.metadata` resolves to an empty object rather than rejecting — iterating the stream is what throws the underlying error.

## Billing [#billing]

Every augmented request adds a fixed surcharge on top of the underlying model spend, applied by the Track D billing pipeline. The default surcharge is **500,000 microcents** ($0.005) per request; deployments can tune it via `WEB_SEARCH_SURCHARGE_MICROCENTS`. Failed and warning-only requests are not surcharged. Augmented requests are also marked non-cacheable — the same prompt run twice will make two search-backend calls and pay the surcharge twice.

## Deployment configuration [#deployment-configuration]

Self-hosted proxies configure web search with four environment variables:

| Variable                          | Default  | Purpose                                                                                 |
| --------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `SEARCH_BACKEND`                  | `exa`    | Backend implementation. Only `exa` is supported today.                                  |
| `EXA_API_KEY`                     | —        | Required when `SEARCH_BACKEND=exa`. Sent as `x-api-key` to `https://api.exa.ai/search`. |
| `WEB_SEARCH_SURCHARGE_MICROCENTS` | `500000` | Fixed per-request surcharge.                                                            |
| `PLUGIN_FETCH_TIMEOUT_MS`         | `5000`   | Abort a search-backend request that hasn't returned within this many milliseconds.      |

Managed RouteShift tenants ship with the Exa backend enabled out of the box; you only need to opt in per request.

## Errors [#errors]

| Response                                  | Status | When                                                                                           |
| ----------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `invalid_plugin`                          | 400    | `plugins` isn't an array, contains a non-object entry, or references an unsupported plugin id. |
| `plugin_backend_not_configured` (warning) | 200    | Optional plugin skipped because the backend isn't wired up.                                    |
| `plugin_backend_failed` (warning)         | 200    | Optional plugin skipped because the backend errored or timed out.                              |
| `plugin_required_failed`                  | 502    | A `required: true` plugin failed — no upstream call was made.                                  |

Warnings are attached to the request log's `plugin_warnings` column so you can spot silent degradation from the dashboard without parsing every response.


# AIS Maritime schema (/codex/schemas/ais-maritime)



The AIS Maritime dataset contains \~1.4M normalized vessel positions sourced from terrestrial and satellite AIS receivers, enriched with vessel identity from IMO registries, behavior anomaly detection, and linkage to Codex port events. Records are ingested continuously and published as monthly immutable snapshots.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

### Vessel identity [#vessel-identity]

| Field         | Type    | Nullable | Description                                                                                                                             |
| ------------- | ------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------- |
| `imo`         | integer |    yes   | IMO number (7-digit). Primary vessel identifier per IMO A.600(15).                                                                      |
| `mmsi`        | string  |    yes   | Maritime Mobile Service Identity (9-digit). Fallback identifier.                                                                        |
| `vessel_name` | string  |    yes   | Vessel name (max 20 ASCII characters per AIS message 5).                                                                                |
| `call_sign`   | string  |    yes   | Radio call sign (max 7 characters).                                                                                                     |
| `flag_state`  | string  |    yes   | ISO 3166-1 alpha-3 country code.                                                                                                        |
| `vessel_type` | string  |    yes   | Codex 6-category enum: `container`, `tanker_crude`, `tanker_product`, `bulker`, `fishing`, `other`. Raw ITU code preserved in metadata. |
| `dwt`         | numeric |    yes   | Deadweight tonnage in metric tonnes.                                                                                                    |
| `length_oa`   | numeric |    yes   | Length overall in meters.                                                                                                               |
| `beam`        | numeric |    yes   | Beam in meters.                                                                                                                         |
| `draught`     | numeric |    yes   | Draught in meters.                                                                                                                      |

### Position and kinematics [#position-and-kinematics]

| Field        | Type        | Nullable | Description                                                                                 |
| ------------ | ----------- | :------: | ------------------------------------------------------------------------------------------- |
| `lat`        | float       |    no    | WGS84 latitude.                                                                             |
| `lng`        | float       |    no    | WGS84 longitude.                                                                            |
| `speed`      | float       |    yes   | Speed over ground in knots (0.1 kn resolution).                                             |
| `course`     | float       |    yes   | Course over ground in degrees (0.1° resolution).                                            |
| `heading`    | float       |    yes   | True heading in degrees (1° resolution).                                                    |
| `nav_status` | string      |    yes   | AIS navigation status (0–15). Codex emits both the numeric code and a human-readable label. |
| `rot`        | float       |    yes   | Rate of turn in degrees per minute (decoded from AIS-coded ±127 value).                     |
| `timestamp`  | timestamptz |    no    | UTC timestamp of the position fix.                                                          |
| `h3_index`   | string      |    no    | H3 resolution-8 cell derived from `lat`/`lng`.                                              |

### Codex enrichments [#codex-enrichments]

| Field                   | Type    | Nullable | Description                                                                                                                          |
| ----------------------- | ------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------ |
| `behavior_anomaly_flag` | boolean |    no    | `true` when kinematic or behavioral anomaly detected (AIS gap, speed anomaly, or route deviation).                                   |
| `port_event_id`         | UUID    |    yes   | Links to the corresponding event in [Events Timeline](/codex/schemas/events-timeline) when the position falls inside a port polygon. |
| `beneficial_owner_urn`  | string  |    yes   | Entity resolution link to the vessel's beneficial owner.                                                                             |
| `sanctioned_owner`      | boolean |    yes   | `true` when the beneficial owner appears on a sanctions list.                                                                        |

## Vessel types [#vessel-types]

The raw ITU vessel type code (0–99) is preserved in `metadata.itu_vessel_type_code`. Codex normalizes vessels into six categories for consistent filtering:

| Category         | Description                  |
| ---------------- | ---------------------------- |
| `container`      | Container ships              |
| `tanker_crude`   | Crude oil tankers            |
| `tanker_product` | Product and chemical tankers |
| `bulker`         | Dry bulk carriers            |
| `fishing`        | Fishing vessels              |
| `other`          | All other vessel types       |

## Navigation status codes [#navigation-status-codes]

| Code | Label                      |
| ---- | -------------------------- |
| 0    | Under way using engine     |
| 1    | At anchor                  |
| 2    | Not under command          |
| 3    | Restricted maneuverability |
| 4    | Constrained by draught     |
| 5    | Moored                     |
| 7    | Engaged in fishing         |
| 8    | Under way sailing          |


  AIS positions in the Codex dataset are compressed to one per minute per vessel. In Overwatch, live positions are kept at full resolution for 7 days and then [downsampled through progressive tiers](/overwatch/data-retention). Both raw and compressed views are available depending on your tier.


## Join keys [#join-keys]

| Key                    |  Presence | Notes                                                             |
| ---------------------- | :-------: | ----------------------------------------------------------------- |
| `record_id`            |   always  | APRS URN                                                          |
| `chunk_id`             |   always  | Deterministic from `record_id`                                    |
| `imo`                  |   often   | Primary vessel identity. Null for small craft without IMO numbers |
| `mmsi`                 |   always  | Fallback vessel identity                                          |
| `h3_index`             |   always  | H3 resolution-8 spatial key                                       |
| `port_event_id`        | sometimes | Links to Events Timeline for in-port positions                    |
| `beneficial_owner_urn` | sometimes | Entity resolution link to beneficial owner                        |

## Example query [#example-query]

Find vessels flagged as anomalous near a specific port in the last 30 days:

```sql
SELECT
  record_id,
  vessel_name,
  imo,
  mmsi,
  timestamp,
  speed,
  nav_status,
  behavior_anomaly_flag,
  sanctioned_owner
FROM read_parquet('ais-maritime-2026-04.parquet')
WHERE h3_index = '88283082b9fffff'
  AND behavior_anomaly_flag = true
  AND timestamp >= now() - interval '30 days'
ORDER BY timestamp DESC;
```

## Known limitations [#known-limitations]

* `imo` is null for small craft, fishing vessels, and some flag-of-convenience registrations. Use `mmsi` as a fallback.
* `vessel_type` normalization collapses 99 ITU codes into 6 categories — check `metadata.itu_vessel_type_code` when you need the original classification.
* `beneficial_owner_urn` is populated by the entity resolution pipeline and may be null for recently ingested positions.
* Position compression (1-per-minute) means sub-minute maneuvers are not visible in the default view.


# Civic Intelligence schema (/codex/schemas/civic-intelligence)



The Civic Intelligence dataset contains \~517K records sourced from Granicus transcripts, Legistar council matters, and Chicago ELMS, plus historical CivicPlus records. Records are collected daily and published as monthly immutable snapshots.


  As of April 2026, the `council_decisions`, `zoning_variances`, and `environmental_reviews` tables are now actively populated. Legistar-sourced records can use an [HTML collection path](#html-collection-mode) for cities where the JSON API is no longer accessible, and California environmental reviews are sourced from the CEQANet registry. EPA EIS records are not yet available — see [known limitations](#known-limitations) for details.


Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field                   | Type           | Nullable | Description                                                                                                     |
| ----------------------- | -------------- | :------: | --------------------------------------------------------------------------------------------------------------- |
| `jurisdiction_slug`     | string         |    no    | Civic jurisdiction identifier (`city-slug-state`).                                                              |
| `h3_index`              | string         |    yes   | H3 resolution-8 cell derived from meeting or parcel location.                                                   |
| `document_type`         | enum           |    no    | Record classification. See [document types](#document-types).                                                   |
| `source`                | enum           |    no    | Originating system (`granicus`, `legistar`, `legistar_html`, `civicplus`, `chicago_elms`, `ceqanet`, `manual`). |
| `source_id`             | string         |    yes   | Source-native identifier (Granicus clip ID, Legistar matter ID).                                                |
| `committee_name`        | string         |    yes   | Committee or body that owned the proceeding.                                                                    |
| `duration_min`          | integer        |    yes   | Meeting duration in minutes (transcripts only).                                                                 |
| `word_count`            | integer        |    yes   | Transcript word count.                                                                                          |
| `summary`               | text           |    yes   | LLM-generated summary. Max 500 chars in `llm_text` view, full length in Parquet.                                |
| `raw_text`              | text           |    yes   | Source transcript or matter body.                                                                               |
| `entities_extracted`    | JSON array     |    yes   | Extracted entities with role, sentiment, and URN. See [entities](#entities).                                    |
| `blockers`              | JSON array     |    yes   | Approval blockers from a controlled vocabulary. See [blockers](#blockers).                                      |
| `contingency_dag`       | JSON object    |    yes   | DAG of conditional approvals. See [contingency DAG](#contingency-dag).                                          |
| `language_signals`      | JSON array     |    yes   | Detected topical signals from a controlled vocabulary.                                                          |
| `sentiment_polarity`    | enum           |    no    | `positive`, `neutral`, or `negative`.                                                                           |
| `topic_velocity`        | numeric        |    yes   | Rate-of-mentions signal for this topic in this jurisdiction.                                                    |
| `momentum_score`        | numeric \[0,1] |    yes   | Confidence-weighted aggregate score.                                                                            |
| `upzoning_probability`  | numeric \[0,1] |    yes   | Classifier-estimated probability of density-increasing zoning change. See [scores](#scores).                    |
| `hostility_index`       | numeric \[0,1] |    yes   | Aggregate of hostile-sentiment mentions and opposition-coded signals.                                           |
| `litigation_risk_score` | numeric \[0,1] |    yes   | Probability of formal legal challenge within 24 months.                                                         |
| `source_url`            | URL            |    yes   | Public-facing source link (council packet PDF, meeting recording).                                              |

## Document types [#document-types]

| Value                  | Description                                                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `council_meeting`      | Full council or board meeting (transcript or minutes)                                                                                  |
| `zoning_vote`          | Council or Planning Commission vote on a zoning item                                                                                   |
| `rezoning_hearing`     | Public hearing on a proposed rezoning                                                                                                  |
| `variance_hearing`     | Zoning board of adjustment or variance hearing                                                                                         |
| `environmental_review` | CEQA/NEPA or state-level environmental review. California records sourced from CEQANet; federal EPA EIS records are not yet available. |
| `capital_improvement`  | Capital improvement plan item                                                                                                          |
| `code_enforcement`     | Code enforcement proceeding                                                                                                            |
| `tax_assessment`       | Tax assessment appeal or action                                                                                                        |
| `building_inspection`  | Inspection outcome                                                                                                                     |
| `foia_request`         | Filed FOIA or public-records request                                                                                                   |
| `planning_matter`      | Other planning matter (Legistar catch-all)                                                                                             |
| `civic_document`       | Uncategorized civic document (low classification confidence)                                                                           |

## Entities [#entities]

The `entities_extracted` field contains an array of entities mentioned in the record. Each entity includes:

```json
{
  "name": "Kenyatta Johnson",
  "role": "councilmember",
  "sentiment": "supportive",
  "entity_urn": "urn:aprs:entity:person:k-johnson-phila",
  "quote_span": [12481, 12723],
  "mention_count": 7
}
```

**Role values:** `councilmember`, `mayor`, `planning_commissioner`, `zoning_board_member`, `developer`, `resident`, `attorney`, `city_agency_staff`, `state_agency_staff`, `nonprofit_representative`, `business_owner`, `expert_witness`, `other`.

**Sentiment values:** `supportive`, `favorable`, `neutral`, `concerned`, `opposed`, `hostile`.


  `entity_urn` is populated by the entity resolution pipeline. Records where resolution has not yet run will have null URNs.


## Blockers [#blockers]

Ordered array of blocker tags identified by the LLM as standing between a proceeding and final approval:

| Tag                                       | Meaning                                                    |
| ----------------------------------------- | ---------------------------------------------------------- |
| `awaiting_eis` / `awaiting_ceqa`          | Environmental review incomplete                            |
| `community_opposition`                    | Organized opposition beyond expected public comment        |
| `litigation_threat` / `active_litigation` | Legal challenge threatened or in progress                  |
| `design_revision_required`                | Design changes needed before approval                      |
| `affordability_covenant_negotiation`      | Affordability terms under negotiation                      |
| `traffic_study_pending`                   | Traffic impact study not complete                          |
| `historic_preservation_review`            | Historic district review required                          |
| `infrastructure_funding_gap`              | Insufficient infrastructure funding                        |
| `inter_agency_coordination`               | Requires another jurisdiction's sign-off                   |
| `political_holdover`                      | No movement across multiple meetings with no stated reason |

## Contingency DAG [#contingency-dag]

The `contingency_dag` field represents conditional approval chains as a directed acyclic graph:

```json
{
  "nodes": [
    { "id": "n1", "label": "Council final vote", "status": "pending" },
    { "id": "n2", "label": "Planning Commission recommendation", "status": "approved", "date": "2024-02-01" },
    { "id": "n3", "label": "Traffic study", "status": "pending" }
  ],
  "edges": [
    { "from": "n2", "to": "n1" },
    { "from": "n3", "to": "n1" }
  ]
}
```

Node status values: `pending`, `approved`, `denied`, `withdrawn`, `deferred`.

## Scores [#scores]

### Upzoning probability [#upzoning-probability]

Classifier-estimated probability that the proceeding results in zoning changes allowing greater density or use intensity. Built with DistilBERT fine-tuned on council minutes with labeled upzoning outcomes. Features include `language_signals`, entity sentiment distribution, `document_type`, and historical base rate by jurisdiction.

* `>= 0.600` — flagged as "likely"
* `>= 0.850` — flagged as "highly likely"


  The training corpus is weighted toward San Francisco, Philadelphia, and Chicago. Probability calibration for smaller jurisdictions may be less accurate.


### Hostility index [#hostility-index]

Aggregate of hostile-sentiment entity mentions and opposition-coded language signals, normalized to document length. Predicts procedural delay, not outcome.

### Litigation risk score [#litigation-risk-score]

Probability of a formal legal challenge (lawsuit, appeal to state board) within 24 months. Built with a gradient boosted classifier trained on historic filings matched to upstream proceedings. Features include `hostility_index`, presence of `attorney` role in entities, `litigation_threat` blocker tag, and jurisdiction base rate.

* `>= 0.700` — flagged as "high risk"

## Join keys [#join-keys]

| Key                 |   Presence   | Notes                                                            |
| ------------------- | :----------: | ---------------------------------------------------------------- |
| `record_id`         |    always    | APRS URN                                                         |
| `chunk_id`          |    always    | Deterministic from `record_id`                                   |
| `h3_index`          |     often    | Null when no location is attributable                            |
| `event_id`          |     often    | Present when mapped to Events Timeline; null for routine filings |
| `jurisdiction_slug` |    always    | Required on every record                                         |
| `entity_urn`        | via entities | Through `entities_extracted[].entity_urn`                        |
| `parcel_id`         |   sometimes  | Present for zoning votes and variances                           |

## Example query [#example-query]

Find high litigation-risk zoning votes in Philadelphia:

```sql
SELECT
  record_id,
  occurred_at,
  summary,
  upzoning_probability,
  litigation_risk_score,
  entities_extracted
FROM read_parquet('civic-intelligence-2026-04.parquet')
WHERE jurisdiction_slug = 'philadelphia-pa'
  AND document_type = 'zoning_vote'
  AND litigation_risk_score >= 0.7
ORDER BY occurred_at DESC
LIMIT 10;
```

## HTML collection mode [#html-collection-mode]

Legistar provides a JSON API for accessing council matters, but many cities have restricted API access behind authentication tokens. When the JSON API is unavailable for a jurisdiction, the collector can switch to an HTML collection mode that scrapes the same data from Legistar's public web pages.

### How it works [#how-it-works]

The HTML collector follows the same three-page navigation path a user would on a Legistar site:

1. **Calendar page** — the collector reads the meeting calendar to find upcoming and recent meetings for zoning-related bodies.
2. **Meeting detail page** — for each relevant meeting, the collector retrieves linked legislation items.
3. **Legislation detail page** — each legislation item is scraped for matter ID, file number, title, type, status, and key dates (introduced, on agenda, final action).

The resulting records are normalized into the same schema as JSON API records, so downstream consumers see no difference in field names or structure.

### Zoning variance filtering [#zoning-variance-filtering]

The zoning variance collector uses keyword-based filtering to identify relevant records from the full stream of council matters. Records are included if **any** of the following match:

**Body keywords** — checked against the legislative body or committee name:

* `zoning`
* `board of appeals`
* `board of adjustment`
* `planning commission`
* `land use`

**Matter type keywords** — checked against the matter type and title:

* `variance`
* `conditional use`
* `special permit`
* `special use`
* `cup`

A record passes the filter if it matches on body name, matter type, or title. This is intentionally broad so that a variance filed under a generically named committee is still captured if the title mentions the relevant keywords.


  These filters differ from the ones used by the council monitor, which targets broader development-related activity (rezoning, demolition, TIF districts, etc.). The zoning variance collector is narrower and focused specifically on variance and conditional-use proceedings.


### Date handling [#date-handling]

Records collected via the HTML path may include dates in `m/d/YYYY` format (for example, `3/15/2026`) rather than the ISO format returned by the JSON API (`2026-03-15T00:00:00`). The collector normalizes all date formats before storage, so `occurred_at` and other date fields are always stored as ISO dates regardless of the collection path.

### Identifying HTML-sourced records [#identifying-html-sourced-records]

Records collected via the HTML path have `source` set to `legistar_html`. You can use this to distinguish them from JSON API records (`source = 'legistar'`) in queries:

```sql
SELECT source, count(*)
FROM read_parquet('civic-intelligence-2026-04.parquet')
WHERE document_type IN ('zoning_vote', 'variance_hearing')
GROUP BY source;
```

## Signal extraction backend [#signal-extraction-backend]

LLM-based signal extraction (used to populate `entities_extracted`, `language_signals`, `blockers`, and item-level fields like `outcome`, `units`, and `dollar_amount`) runs on a configurable backend. Schema-constrained classification work defaults to a local model; the hosted Anthropic backend is opt-in.

### Backend selection [#backend-selection]

The Granicus extractor selects a backend based on the `CIVIC_EXTRACTOR` environment variable:

| Value              | Backend                            | Notes                                                                                                                             |
| ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `ollama` (default) | Local Ollama runtime               | Uses the `qwen3.6:35b-a3b` model with `format: json` and reasoning disabled (`think: false`) so JSON output is returned directly. |
| `anthropic`        | Claude Haiku via the Anthropic API | Requires `ANTHROPIC_API_KEY`. Use for one-off audits or when the local runtime is unavailable.                                    |

When `CIVIC_EXTRACTOR` is unset or set to `ollama`, the extractor calls the local runtime only — there is no silent fallback to Anthropic. If the local runtime returns a non-200 response or invalid JSON, the record is skipped and `extracted_signals` remains null. Re-run the extractor after the local runtime is restored to populate skipped records.

### Configuration [#configuration]

| Variable            | Default                       | Description                                                                               |
| ------------------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
| `CIVIC_EXTRACTOR`   | `ollama`                      | Backend selector: `ollama` or `anthropic`.                                                |
| `OLLAMA_BASE_URL`   | `http://100.94.177.111:11434` | Ollama host. Override for local development or alternate inference hosts.                 |
| `OLLAMA_MODEL`      | `qwen3.6:35b-a3b`             | Ollama model tag. The model must accept the `think` option and return JSON in `response`. |
| `ANTHROPIC_API_KEY` | unset                         | Required only when `CIVIC_EXTRACTOR=anthropic`.                                           |

### Output schema [#output-schema]

Both backends are prompted with the same schema, so downstream consumers — including the `civic_decision_signals` materialized view — observe identical field shapes regardless of which backend produced a record. Each item carries `item_type`, `outcome`, `units`, `sqft`, `dollar_amount`, `h3_signal`, `development_sentiment`, and `high_signal`.

### Example [#example]

Run a one-off backfill against the hosted Anthropic backend:

```bash
export CIVIC_EXTRACTOR=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
python -m groundswell council.granicus --city sf --since 2026-01-01
```

Run the same command against a locally hosted Ollama instance:

```bash
export CIVIC_EXTRACTOR=ollama
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=qwen3.6:35b-a3b
python -m groundswell council.granicus --city sf --since 2026-01-01
```

## Known limitations [#known-limitations]

* Jurisdictional coverage is uneven — dense for San Francisco, Philadelphia, and Boston; sparse for sunbelt growth markets.
* CivicPlus ingestion has been retired. The upstream `/AgendaCenter/ViewFile/...` URL pattern the scraper depended on is no longer served by the tracked city domains, so no new records with `source = 'civicplus'` are being landed. Historical CivicPlus rows remain valid and queryable, and the `civicplus` value stays in the `source` enum for backward compatibility. Coverage will resume once a rebuilt scraper ships.
* `language_signals` vocabulary is English-only. Bilingual meetings may underperform on signal extraction.
* Transcripts lag real-time by 24–72 hours. Use `occurred_at` for event-time analysis, not `ingested_at`.
* The legacy `document_date` field is retained for backward compatibility. Use `occurred_at` instead.
* Legistar HTML-sourced records (`source = 'legistar_html'`) may have null date fields when the source page uses non-standard labels. Most major cities — including New York City, Seattle, San Francisco, and Chicago — now resolve titles, sponsoring bodies, and dates through multiple fallback labels, but some jurisdictions may still return nulls. Filter on `occurred_at IS NOT NULL` if your query requires dates.
* EPA EIS environmental reviews are not yet available. The `environmental_review` document type currently covers California CEQA filings (via CEQANet) only. Federal NEPA coverage is planned.
* Records collected while the local extraction backend was unreachable have null `extracted_signals` and may also have empty `raw_text` if the upstream Granicus transcript fetch did not complete. These records require both the upstream fetch and the extractor to be re-run before signals appear. See [signal extraction backend](#signal-extraction-backend) for backend configuration.


# Events Timeline schema (/codex/schemas/events-timeline)



The Events Timeline is the unified event stream that connects every Axiom product. It contains \~1.7M events from 16+ source normalizers covering permits, council votes, AIS dark events, port calls, regulatory filings, POI lifecycle changes, crop health alerts, and more. Every other Codex dataset references an `event_id` from this timeline, making it the **graph spine** across the catalog.

Records are ingested continuously and published as monthly immutable snapshots. Every record inherits the full [APRS envelope](/codex/normalization-standard) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field                | Type          | Nullable | Description                                                                                         |
| -------------------- | ------------- | :------: | --------------------------------------------------------------------------------------------------- |
| `event_type`         | dotted string |    no    | Hierarchical event type. See [event taxonomy](#event-taxonomy).                                     |
| `event_category`     | enum          |    no    | High-level grouping: `maritime`, `civic`, `regulatory`, `poi`, `environmental`, `economic`, `risk`. |
| `entity_id`          | string        |    no    | Canonical key for the affected entity. Shape depends on `entity_type`.                              |
| `entity_type`        | enum          |    no    | Type of the affected entity. See [entity types](#entity-types).                                     |
| `entity_name`        | string        |    yes   | Human-readable name (display only).                                                                 |
| `location`           | PostGIS Point |    yes   | WGS84 geometry. Use `h3_index` for joins.                                                           |
| `location_name`      | string        |    yes   | Human-readable location description.                                                                |
| `h3_index`           | string        |    yes   | H3 resolution-8 cell derived from `location`.                                                       |
| `started_at`         | timestamptz   |    no    | When the real-world event began.                                                                    |
| `resolved_at`        | timestamptz   |    yes   | When the event closed. Null if still open or point-in-time.                                         |
| `magnitude`          | float         |    yes   | Event-specific magnitude. Unit varies by `event_type`. See [magnitude units](#magnitude-units).     |
| `confidence`         | float \[0,1]  |    yes   | Pipeline confidence that the event is real.                                                         |
| `source`             | string        |    no    | Originating pipeline (`aisstream`, `socrata`, `granicus`, etc.).                                    |
| `source_ref`         | string        |    yes   | Source-native reference for re-fetch.                                                               |
| `product`            | enum          |    no    | Generating product: `locus`, `overwatch`, or `codex`.                                               |
| `downstream_outcome` | string        |    yes   | Post-hoc outcome annotation from cascade detectors.                                                 |
| `outcome_lag_days`   | integer       |    yes   | Days between this event and its downstream outcome.                                                 |
| `metadata`           | JSONB         |    yes   | Event-specific overflow fields. See [metadata keys](#metadata-keys).                                |
| `jurisdiction_slug`  | string        |    yes   | Populated for civic and regulatory events.                                                          |

## Event taxonomy [#event-taxonomy]

Event types use a `{domain}.{verb}` convention. You can filter at the family level (`event_type LIKE 'port.%'`) or by specific action.

### Maritime events [#maritime-events]

| Type                     | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| `port.entered`           | Vessel crossed port polygon inbound                               |
| `port.anchored`          | Vessel reported anchored status inside port                       |
| `port.berthed`           | Vessel matched to a specific berth                                |
| `port.departed`          | Vessel crossed port polygon outbound                              |
| `visit.in_progress`      | Open vessel visit, no departure yet                               |
| `visit.completed`        | Paired entry and departure. `magnitude` = visit duration in hours |
| `dark_event`             | AIS gap plus kinematic violation                                  |
| `satellite.{alert_type}` | Per-alert-type subtype (e.g., `vessel_cluster`, `dark_emission`)  |

### Civic events [#civic-events]

| Type                | Description                        |
| ------------------- | ---------------------------------- |
| `council.approved`  | Council vote in favor              |
| `council.denied`    | Council vote against               |
| `council.tabled`    | Motion tabled or deferred          |
| `council.mentioned` | Topic mentioned, no decision       |
| `permit.filed`      | New permit application             |
| `permit.approved`   | Permit approved                    |
| `permit.denied`     | Permit denied                      |
| `permit.expired`    | Permit aged out without completion |
| `permit.completed`  | Work finaled                       |
| `permit.cancelled`  | Withdrawn by applicant             |
| `permit.revoked`    | Revoked by authority               |
| `noise_complaint`   | 311 noise complaint                |
| `business_license`  | New license issued                 |

### Regulatory events [#regulatory-events]

| Type                     | Description                         |
| ------------------------ | ----------------------------------- |
| `regulatory.filing`      | SEC 8-K, 10-K, etc.                 |
| `regulatory.enforcement` | FDA, EPA, or OSHA action            |
| `regulatory.complaint`   | Consumer or worker complaint filing |
| `regulatory.notice`      | Authority notice                    |
| `regulatory.rule`        | Final rule publication              |

### POI events [#poi-events]

| Type                     | Description                    |
| ------------------------ | ------------------------------ |
| `poi.opened`             | First observation of a new POI |
| `poi.active`             | Ongoing POI observation        |
| `poi.temporarily_closed` | Temporary closure              |
| `poi.closed`             | Permanently closed             |

### Environmental events [#environmental-events]

| Type                     | Description                                           |
| ------------------------ | ----------------------------------------------------- |
| `environmental.disaster` | FEMA/NWS disaster declaration                         |
| `crop.ndvi_drop`         | Sentinel-2 NDVI decline. `magnitude` = percent change |
| `crop.ndvi_recovery`     | NDVI recovery                                         |
| `river.{status}`         | Gauge status subtype (`flood`, `action`, `normal`)    |

### Economic events [#economic-events]

| Type                | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `jobs.snapshot`     | Periodic snapshot of active postings per cell. `magnitude` = listing count |
| `migration.inflow`  | Net positive migration. `magnitude` = net persons                          |
| `migration.outflow` | Net negative migration                                                     |
| `trade.{flow_type}` | Customs/CBP trade flow subtype                                             |

### Risk events [#risk-events]

| Type            | Description      |
| --------------- | ---------------- |
| `risk.critical` | Risk score >= 85 |
| `risk.elevated` | Risk score >= 60 |
| `risk.moderate` | Risk score >= 30 |
| `risk.low`      | Risk score \< 30 |

## Entity types [#entity-types]

The shape of `entity_id` depends on `entity_type`:

| Entity type      | `entity_id` shape                     | Example                            |
| ---------------- | ------------------------------------- | ---------------------------------- |
| `vessel`         | IMO number (preferred) or MMSI        | `9432871`                          |
| `parcel`         | `{jurisdiction_slug}:{parcel-number}` | `philadelphia-pa:12-345-678`       |
| `permit`         | `permit:{jurisdiction}:{permit-id}`   | `permit:sf-ca:2024-0412`           |
| `council_matter` | `legistar:{jurisdiction}:{matter-id}` | `legistar:phila-pa:24-0031`        |
| `poi`            | `urn:aprs:record:poi:{source}:{id}`   | `urn:aprs:record:poi:fsq:abc123`   |
| `organization`   | `urn:aprs:entity:company:{id}`        | `urn:aprs:entity:company:acme-llc` |
| `person`         | `urn:aprs:entity:person:{id}`         | `urn:aprs:entity:person:j-doe`     |
| `h3_cell`        | H3 resolution-8 string                | `88283082b9fffff`                  |
| `jurisdiction`   | `jurisdiction_slug`                   | `philadelphia-pa`                  |

## Magnitude units [#magnitude-units]

`magnitude` is polymorphic — its unit depends on `event_type`. Always check `event_type` before comparing magnitude values.

| Event type pattern                          | Unit                               |
| ------------------------------------------- | ---------------------------------- |
| `visit.completed`                           | Hours (visit duration)             |
| `dark_event`                                | Hours (AIS gap)                    |
| `crop.ndvi_*`                               | Percent change vs. 5-year baseline |
| `jobs.snapshot`                             | Count of active postings           |
| `migration.*`                               | Net persons                        |
| `trade.*`                                   | USD value (notional)               |
| `risk.*`                                    | Risk score 0–100                   |
| `permit.*` (with `metadata.declared_value`) | USD value                          |

## Metadata keys [#metadata-keys]

The `metadata` JSONB column holds type-specific fields. Keys are version-bound — a key present in one event type is not guaranteed in another.

| Key                     | Event types            | Description                                                                          |
| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `kinematic_meta`        | `dark_event`           | Implied speed, Froude limit, OU max reach, actual distance, failed tests             |
| `psc_detention_history` | Maritime events        | Port State Control detentions linked to this event                                   |
| `declared_value`        | `permit.*`             | USD value declared on the permit                                                     |
| `voting_tally`          | `council.*`            | `{yes, no, abstain, absent}`                                                         |
| `alert_type_raw`        | `satellite.*`          | Upstream alert code                                                                  |
| `related_event_ids`     | Any                    | Array of `event_id` UUIDs this event is linked to. See [event chains](#event-chains) |
| `mmsi`                  | Maritime               | MMSI when `entity_type='vessel'`                                                     |
| `imo`                   | Maritime               | IMO number when known                                                                |
| `parcel_id`             | Civic (permits/zoning) | Parcel identifier                                                                    |

## Event chains [#event-chains]

Events are often cascading effects of earlier events. The `metadata.related_event_ids` field links events into chains:

* **Maritime dark event chain:** `port.departed` → `dark_event` → `port.entered` (different port)
* **Permit cascade:** `council.approved` → `permit.filed` → `permit.approved` → `permit.completed`
* **Risk cascade:** `regulatory.enforcement` → `risk.critical`

### Traversal example [#traversal-example]

Find every downstream civic event following a dark event within 12 months:

```sql
WITH RECURSIVE chain AS (
  SELECT id, event_type, started_at, metadata
  FROM codex.events_timeline
  WHERE id = 'c5a8e4f2-9b7d-4c1e-b3a5-1f2d8c0e7a93'

  UNION ALL

  SELECT e.id, e.event_type, e.started_at, e.metadata
  FROM codex.events_timeline e
  JOIN chain c
    ON c.id::text = ANY(
      ARRAY(SELECT jsonb_array_elements_text(e.metadata->'related_event_ids'))
    )
  WHERE e.started_at - c.started_at BETWEEN interval '0' AND interval '365 days'
)
SELECT * FROM chain
WHERE event_category = 'civic';
```

## Confidence semantics [#confidence-semantics]

The `confidence` field represents pipeline confidence that the event is real, not a downstream prediction score:

* **Maritime** — AIS signal quality × kinematic model posterior
* **Civic** — LLM extraction confidence × source reliability score
* **Regulatory** — 1.0 for primary-source filings; degraded for secondary mirrors
* **Environmental** — satellite cloud cover × model confidence


  Events with `confidence < 0.4` are excluded from Research and Commercial tier exports by default.


## Join keys [#join-keys]

| Key                 |    Presence   | Notes                                                       |
| ------------------- | :-----------: | ----------------------------------------------------------- |
| `event_id` (= `id`) |     always    | Primary key — the spine across all Codex datasets           |
| `record_id`         |     always    | APRS URN: `urn:aprs:record:event:{product}:{id}`            |
| `chunk_id`          |     always    | Deterministic from `record_id`                              |
| `h3_index`          |     often     | Null for events without geometry (e.g., regulatory filings) |
| `jurisdiction_slug` |     often     | Always for civic and regulatory; sometimes for others       |
| `mmsi`              | maritime only | In `metadata.mmsi`                                          |
| `imo`               | maritime only | In `metadata.imo` (preferred over MMSI)                     |
| `parcel_id`         |   civic only  | In `metadata.parcel_id`                                     |
| `entity_urn`        |     often     | Present for person, organization, and POI entities          |

## Example queries [#example-queries]

### Permit cascades after approved rezonings [#permit-cascades-after-approved-rezonings]

```sql
SELECT
  rez.id             AS rezoning_event_id,
  rez.jurisdiction_slug,
  rez.started_at     AS rezoning_date,
  permit.event_type  AS permit_stage,
  permit.started_at  AS permit_date,
  permit.started_at - rez.started_at AS lag
FROM codex.events_timeline rez
JOIN codex.events_timeline permit
  ON permit.metadata->'related_event_ids' ? rez.id::text
WHERE rez.event_type = 'council.approved'
  AND rez.started_at >= now() - interval '1 year'
  AND permit.event_type LIKE 'permit.%'
ORDER BY rez.jurisdiction_slug, rez.started_at;
```

### All dark events longer than 48 hours [#all-dark-events-longer-than-48-hours]

```sql
SELECT
  entity_name,
  started_at,
  resolved_at,
  magnitude AS gap_hours,
  metadata->'kinematic_meta'->>'implied_speed_kn' AS implied_speed
FROM read_parquet('events-timeline-2026-04.parquet')
WHERE event_type = 'dark_event'
  AND magnitude > 48
ORDER BY magnitude DESC;
```

## Known limitations [#known-limitations]

* `entity_id` shape is polymorphic — you must branch on `entity_type` before joining.
* `magnitude` units vary by event type. See [magnitude units](#magnitude-units) before comparing.
* `related_event_ids` coverage is uneven. Currently populated by maritime and permit normalizers; civic cascade linking is in progress.
* `downstream_outcome` is post-hoc and sparse — only populated once cascade detectors run, which can take 30–90 days.


# LEHD Commuter Flows schema (/codex/schemas/lehd-commuter-flows)



The LEHD Commuter Flows dataset contains \~454K origin-destination pairs derived from Census Bureau LODES v8 (Longitudinal Employer-Household Dynamics). Each pair represents a commute flow between two H3 resolution-8 cells, enriched with income breakdowns, NAICS sector counts, and Codex-computed accessibility indices.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

### Flow identifiers [#flow-identifiers]

| Field                    | Type   | Nullable | Description                                                                                      |
| ------------------------ | ------ | :------: | ------------------------------------------------------------------------------------------------ |
| `origin_h3`              | string |    no    | H3 resolution-8 cell of the workplace (derived from LODES `w_geocode`).                          |
| `destination_h3`         | string |    no    | H3 resolution-8 cell of the residence (derived from LODES `h_geocode`).                          |
| `origin_block_fips`      | string |    no    | Census block FIPS code (15-character) for the workplace. Retained as a Census-native identifier. |
| `destination_block_fips` | string |    no    | Census block FIPS code for the residence.                                                        |
| `metro_slug`             | string |    yes   | Metro area identifier (derived from metro FIPS).                                                 |

### Worker counts [#worker-counts]

| Field                  | Type    | Nullable | Description                                                     |
| ---------------------- | ------- | :------: | --------------------------------------------------------------- |
| `worker_count`         | integer |    no    | Total number of jobs (LODES `S000`).                            |
| `worker_count_lt30k`   | integer |    no    | Jobs with earnings \< $1,250/month (LODES `SE01`).              |
| `worker_count_30to60k` | integer |    no    | Jobs with earnings $1,251–$3,333/month (LODES `SE02`).          |
| `worker_count_gt60k`   | integer |    no    | Jobs with earnings > $3,333/month (LODES `SE03`).               |
| `income_band`          | enum    |    no    | Codex-derived dominant income band: `low`, `mid`, or `high`.    |
| `job_sector_naics`     | string  |    yes   | NAICS sector code with aggregated counts (LODES `SI01`–`SI03`). |

### Codex enrichments [#codex-enrichments]

| Field                 | Type         | Nullable | Description                                                                                                                   |
| --------------------- | ------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------- |
| `accessibility_index` | float \[0,1] |    no    | Codex-computed accessibility score per origin-destination H3 pair. Higher values indicate better transit and commute options. |
| `distance_km`         | float        |    no    | Centroid-to-centroid distance in kilometers between origin and destination H3 cells.                                          |
| `h3_neighbor_rank`    | integer      |    no    | k-ring distance from origin to destination (0 = same cell, 1 = immediate neighbor, etc.).                                     |
| `lehd_year`           | integer      |    no    | Reference year for the LODES data (e.g. `2023`).                                                                              |

## Income bands [#income-bands]

The `income_band` field is derived from the LODES earnings breakdown:

| Band   | Criterion                                     |
| ------ | --------------------------------------------- |
| `low`  | Plurality of workers earn \< $1,250/month     |
| `mid`  | Plurality of workers earn $1,251–$3,333/month |
| `high` | Plurality of workers earn > $3,333/month      |

## Accessibility index [#accessibility-index]

The `accessibility_index` is a Codex-computed score that factors in transit coverage, commute distance, and commute volume between the origin and destination cells. It is useful for identifying well-connected corridors versus underserved commute routes.


  Census LODES data includes noise infusion to protect respondent privacy. Codex preserves this noise as-is — small counts (under \~10 workers) may not reflect exact flows.


## Join keys [#join-keys]

| Key                      | Presence | Notes                                                                    |
| ------------------------ | :------: | ------------------------------------------------------------------------ |
| `record_id`              |  always  | APRS URN                                                                 |
| `chunk_id`               |  always  | Deterministic from `record_id`                                           |
| `origin_h3`              |  always  | Join with Urban Signal Grid, POI Intelligence, or any H3-indexed dataset |
| `destination_h3`         |  always  | Same as above                                                            |
| `origin_block_fips`      |  always  | Census-native identifier for block-level joins                           |
| `destination_block_fips` |  always  | Same as above                                                            |
| `metro_slug`             |   often  | Metro area identifier                                                    |

## Example query [#example-query]

Find the highest-volume commute corridors into a downtown cell:

```sql
SELECT
  origin_h3,
  destination_h3,
  worker_count,
  income_band,
  accessibility_index,
  distance_km
FROM read_parquet('lehd-commuter-flows-2026-04.parquet')
WHERE destination_h3 = '88283082b9fffff'
  AND worker_count >= 50
ORDER BY worker_count DESC
LIMIT 20;
```

## Known limitations [#known-limitations]

* LODES data lags by 2–3 years. The `lehd_year` field indicates the reference year — it does not reflect current conditions.
* Census noise infusion means small cell-pair flows (under \~10 workers) carry significant uncertainty.
* Block-level granularity is collapsed to H3 resolution 8. Multiple Census blocks may map to the same H3 cell.
* `metro_slug` is null for flows in rural areas outside defined metro boundaries.


# OSHA Safety Index schema (/codex/schemas/osha-safety)



The OSHA Safety Index dataset contains 500K+ enforcement actions, inspections, and citations from the Occupational Safety and Health Administration. Each record is linked to EPA Facility Registry Service (FRS) identifiers, classified by NAICS sector, and connected to parent corporate entities through entity resolution.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field               | Type          | Nullable | Description                                                                                                 |
| ------------------- | ------------- | :------: | ----------------------------------------------------------------------------------------------------------- |
| `source_ref`        | string        |    no    | OSHA inspection number.                                                                                     |
| `occurred_at`       | timestamptz   |    no    | Inspection open date.                                                                                       |
| `resolved_at`       | timestamptz   |    yes   | Case close date. Null if still open.                                                                        |
| `entity_id`         | string        |    no    | Establishment identifier.                                                                                   |
| `entity_name`       | string        |    yes   | Establishment name.                                                                                         |
| `location`          | PostGIS Point |    yes   | WGS84 geometry of the establishment.                                                                        |
| `h3_index`          | string        |    yes   | H3 resolution-8 cell.                                                                                       |
| `jurisdiction_slug` | string        |    yes   | Civic jurisdiction where the establishment is located.                                                      |
| `naics_code`        | string        |    no    | 6-digit NAICS code (2022 revision).                                                                         |
| `naics_title`       | string        |    no    | Human-readable NAICS sector title.                                                                          |
| `frs_id`            | string        |    yes   | EPA Facility Registry Service identifier. See [facility linkage](#facility-linkage).                        |
| `inspection_type`   | enum          |    no    | Type of inspection. See [inspection types](#inspection-types).                                              |
| `violation_count`   | integer       |    no    | Number of violations cited in this inspection.                                                              |
| `citation_severity` | enum          |    yes   | Most severe citation issued. See [citation severity](#citation-severity).                                   |
| `penalty_usd`       | numeric       |    yes   | Current penalty amount in USD.                                                                              |
| `hazard_categories` | JSON array    |    yes   | Human-readable hazard labels derived from CFR standards codes. See [hazard categories](#hazard-categories). |
| `parent_entity_urn` | string        |    yes   | Entity resolution link to the parent corporate entity.                                                      |

## Inspection types [#inspection-types]

| Type           | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `Programmed`   | Planned inspection based on industry targeting criteria     |
| `Unprogrammed` | Not planned — triggered by complaint, referral, or accident |
| `Referral`     | Referred by another agency or inspector                     |
| `Complaint`    | Filed by an employee or representative                      |
| `FollowUp`     | Follow-up to a previous inspection                          |
| `Accident`     | Triggered by a workplace accident, injury, or fatality      |

## Citation severity [#citation-severity]

| Severity  | Description                                             |
| --------- | ------------------------------------------------------- |
| `willful` | Employer knowingly committed a violation                |
| `serious` | Substantial probability of death or serious harm        |
| `other`   | Non-serious violation                                   |
| `repeat`  | Substantially similar violation within the last 5 years |

## Facility linkage [#facility-linkage]

Each OSHA record is matched against the EPA Facility Registry Service (FRS) using address, NAICS code, and name heuristics. The match confidence is available in `metadata.frs_match_confidence`.


  Low-confidence FRS matches (below 0.7) are excluded from Commercial-tier exports. Research-tier users see all matches with the confidence score included for filtering.


## Hazard categories [#hazard-categories]

The `hazard_categories` field translates CFR standards references (e.g. `1926.501`) into human-readable labels. A single inspection may cite multiple hazards:

```json
["fall_protection", "scaffolding", "electrical_wiring"]
```

The raw CFR reference codes are preserved in `metadata.cfr_codes`.

## Join keys [#join-keys]

| Key                 |  Presence | Notes                                                              |
| ------------------- | :-------: | ------------------------------------------------------------------ |
| `record_id`         |   always  | APRS URN                                                           |
| `chunk_id`          |   always  | Deterministic from `record_id`                                     |
| `h3_index`          |   often   | Null for establishments without geocodable addresses               |
| `naics_code`        |   always  | Join with POI Intelligence, LEHD, and other NAICS-indexed datasets |
| `frs_id`            |   often   | EPA Facility Registry Service link                                 |
| `jurisdiction_slug` |   often   | Civic jurisdiction                                                 |
| `parent_entity_urn` | sometimes | Corporate entity resolution link                                   |

## Example query [#example-query]

Find the top penalty inspections in a NAICS sector with willful citations:

```sql
SELECT
  source_ref,
  entity_name,
  naics_title,
  occurred_at,
  citation_severity,
  violation_count,
  penalty_usd,
  hazard_categories
FROM read_parquet('osha-safety-2026-04.parquet')
WHERE naics_code LIKE '2362%'
  AND citation_severity = 'willful'
  AND penalty_usd > 0
ORDER BY penalty_usd DESC
LIMIT 20;
```

## Known limitations [#known-limitations]

* Only public OSHA establishment search data is included. Confidential injury and illness data per 29 CFR 1904 is not available.
* `frs_id` linkage uses heuristic matching — verify `metadata.frs_match_confidence` before relying on facility cross-references.
* `parent_entity_urn` is populated by the entity resolution pipeline and may be null for recently ingested records.
* Penalty amounts reflect the current (potentially reduced) penalty, not the originally proposed amount. Check `metadata.proposed_penalty_usd` for the initial figure.


# Permit Signals schema (/codex/schemas/permit-signals)



The Permit Signals dataset contains \~2.1M building, demolition, zoning, and construction permits across U.S. jurisdictions. Each permit is enriched with LLM-classified scope extraction, parcel linkage, and developer entity resolution. Permits are modeled as cascading lifecycle events that link back to the [Events Timeline](/codex/schemas/events-timeline).

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field                  | Type        | Nullable | Description                                                                                        |
| ---------------------- | ----------- | :------: | -------------------------------------------------------------------------------------------------- |
| `event_id`             | UUID        |    no    | Links to the corresponding event in Events Timeline.                                               |
| `source_ref`           | string      |    no    | Jurisdiction-native permit number.                                                                 |
| `permit_type`          | enum        |    no    | Normalized permit classification. See [permit types](#permit-types).                               |
| `event_type`           | string      |    no    | Lifecycle stage (e.g. `permit.filed`, `permit.approved`). See [lifecycle](#permit-lifecycle).      |
| `occurred_at`          | timestamptz |    no    | Timestamp of this lifecycle stage.                                                                 |
| `effective_from`       | timestamptz |    yes   | Start of permit validity period.                                                                   |
| `effective_to`         | timestamptz |    yes   | End of permit validity period.                                                                     |
| `issuing_agency`       | string      |    no    | Name of the issuing government agency.                                                             |
| `jurisdiction_slug`    | string      |    no    | Civic jurisdiction identifier.                                                                     |
| `address`              | string      |    yes   | Property address.                                                                                  |
| `parcel_id`            | string      |    yes   | Assessor parcel identifier.                                                                        |
| `h3_index`             | string      |    yes   | H3 resolution-8 cell derived from the property location.                                           |
| `declared_value`       | numeric     |    yes   | Dollar value declared on the permit application (USD).                                             |
| `scope_extract`        | JSON object |    yes   | LLM-extracted structured description of the work scope. See [scope extraction](#scope-extraction). |
| `applicant_entity_urn` | string      |    yes   | Entity resolution link to the applicant or developer.                                              |

## Permit types [#permit-types]

Jurisdiction-native permit type values are normalized to a 10-value enum. The raw source value is preserved in `metadata.source_permit_type`.

| Type               | Description                               |
| ------------------ | ----------------------------------------- |
| `new_construction` | New building construction                 |
| `addition`         | Addition to an existing structure         |
| `alteration`       | Interior or exterior alteration           |
| `demolition`       | Full or partial demolition                |
| `change_of_use`    | Change of occupancy or use classification |
| `zoning`           | Variance, rezoning, or special exception  |
| `signage`          | Sign permits                              |
| `mechanical`       | HVAC, plumbing, or electrical work        |
| `fire`             | Fire alarm or suppression system          |
| `other`            | Uncategorized permit types                |

## Permit lifecycle [#permit-lifecycle]

Each permit progresses through a series of stages, modeled as events linked by `metadata.related_event_ids`:

```text
permit.filed → permit.approved → permit.completed
                    ↘ permit.denied
                    ↘ permit.cancelled
                    ↘ permit.revoked
                    ↘ permit.expired
```

Query the full lifecycle chain by following `metadata.related_event_ids` in the [Events Timeline](/codex/schemas/events-timeline#event-chains).

## Scope extraction [#scope-extraction]

The `scope_extract` field contains a structured JSON object produced by an LLM that parses the free-text work description on the permit application. A typical output:

```json
{
  "work_type": "interior_renovation",
  "floors_affected": [2, 3],
  "units_added": 4,
  "square_footage": 12500,
  "use_change": "office_to_residential",
  "confidence": 0.82
}
```


  Scope extraction is confidence-rated. A `confidence` value below 0.7 suggests the LLM had difficulty parsing the source text — review the raw permit description before relying on extracted fields.


## Join keys [#join-keys]

| Key                    |  Presence | Notes                                            |
| ---------------------- | :-------: | ------------------------------------------------ |
| `record_id`            |   always  | APRS URN                                         |
| `chunk_id`             |   always  | Deterministic from `record_id`                   |
| `event_id`             |   always  | Links to Events Timeline                         |
| `h3_index`             |   often   | Null for permits without geocodable addresses    |
| `jurisdiction_slug`    |   always  | Civic jurisdiction identifier                    |
| `parcel_id`            |   often   | Assessor parcel identifier                       |
| `applicant_entity_urn` | sometimes | Entity resolution link to applicant or developer |

## Example query [#example-query]

Find high-value new construction permits filed in a jurisdiction in the last 90 days:

```sql
SELECT
  source_ref,
  permit_type,
  event_type,
  occurred_at,
  declared_value,
  scope_extract,
  address
FROM read_parquet('permit-signals-2026-04.parquet')
WHERE jurisdiction_slug = 'philadelphia-pa'
  AND permit_type = 'new_construction'
  AND event_type = 'permit.filed'
  AND occurred_at >= now() - interval '90 days'
  AND declared_value >= 1000000
ORDER BY declared_value DESC;
```

## Known limitations [#known-limitations]

* Jurisdiction-native permit types vary widely. The 10-value normalized enum may lose specificity — check `metadata.source_permit_type` for the original classification.
* `scope_extract` quality depends on the structure of the source permit text. Jurisdictions with free-form descriptions produce lower-confidence extractions.
* `parcel_id` formats vary by jurisdiction. Use `jurisdiction_slug` + `parcel_id` as the composite key when joining with external assessor data.
* Lifecycle chain coverage depends on jurisdictional reporting. Some jurisdictions only publish filed and approved stages.


# POI Intelligence schema (/codex/schemas/poi-intelligence)



The POI Intelligence dataset contains \~89K points of interest across U.S. metros sourced from Foursquare, OpenStreetMap, Google Places, and manual verification. Each POI is enriched with industry classification (NAICS and ISIC), walkability and transit scores, and a pioneer-flag indicator for recently opened businesses in growth areas.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field            | Type             | Nullable | Description                                                                                                                  |
| ---------------- | ---------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------- |
| `poi_id`         | string           |    no    | Primary POI identifier.                                                                                                      |
| `name`           | string           |    no    | Business or location name.                                                                                                   |
| `category`       | string           |    no    | Top-level category (e.g. `restaurant`, `retail`, `office`).                                                                  |
| `subcategory`    | string           |    yes   | Refined category (e.g. `fast_casual`, `coworking`).                                                                          |
| `naics_code`     | string           |    yes   | 6-digit NAICS industry code (2022 revision).                                                                                 |
| `isic_code`      | string           |    yes   | ISIC Rev. 4 international industry code.                                                                                     |
| `lat`            | float            |    no    | WGS84 latitude.                                                                                                              |
| `lng`            | float            |    no    | WGS84 longitude.                                                                                                             |
| `h3_index`       | string           |    no    | H3 resolution-8 cell.                                                                                                        |
| `address`        | string           |    yes   | Full postal address.                                                                                                         |
| `phone`          | string           |    yes   | Contact phone number.                                                                                                        |
| `website`        | URL              |    yes   | Business website.                                                                                                            |
| `is_pioneer`     | boolean          |    no    | `true` when the POI opened in the last 12 months in a growth context. See [pioneer classification](#pioneer-classification). |
| `walk_score`     | integer \[0,100] |    yes   | Walkability score for the location.                                                                                          |
| `transit_score`  | integer \[0,100] |    yes   | Transit accessibility score.                                                                                                 |
| `reviews_sample` | JSON array       |    yes   | Up to 5 representative reviews.                                                                                              |
| `photo_count`    | integer          |    yes   | Number of photos available from source feeds.                                                                                |
| `source_feed`    | enum             |    no    | Originating source: `foursquare`, `osm`, `google`, `manual`.                                                                 |

## Pioneer classification [#pioneer-classification]

A POI is classified as a "pioneer" when it meets all three criteria:

1. Opened within the last 12 months
2. Located in a cell with a rising [Urban Signal Grid](/codex/schemas/urban-signal-grid) composite score
3. Nearby area shows positive net migration and recent construction permits

Pioneer POIs are early indicators of neighborhood transformation. Use the `is_pioneer` flag to identify emerging commercial corridors before they appear in traditional market reports.

## Industry classification [#industry-classification]

Each POI carries up to three parallel industry taxonomies:

| Taxonomy       | Field                      | Coverage         |
| -------------- | -------------------------- | ---------------- |
| Codex category | `category` / `subcategory` | 100% of records  |
| NAICS          | `naics_code`               | \~85% of records |
| ISIC           | `isic_code`                | \~80% of records |

Use `naics_code` for cross-joins with OSHA Safety, LEHD Commuter Flows, and other government datasets that use NAICS classification.

## Source feeds and licensing [#source-feeds-and-licensing]

| Source        | License    | Notes                         |
| ------------- | ---------- | ----------------------------- |
| OpenStreetMap | ODbL-1.0   | Available in all tiers        |
| Foursquare    | CC-BY-4.0  | Research and Commercial tiers |
| Google Places | Restricted | Commercial tier only          |


  Multi-source identity resolution maps duplicate entries from different feeds to a single `poi_id`. Source-native identifiers are preserved in the `identifier` array within metadata.


## Join keys [#join-keys]

| Key          |  Presence | Notes                                                         |
| ------------ | :-------: | ------------------------------------------------------------- |
| `record_id`  |   always  | APRS URN                                                      |
| `chunk_id`   |   always  | Deterministic from `record_id`                                |
| `poi_id`     |   always  | Primary POI identifier                                        |
| `h3_index`   |   always  | H3 resolution-8 spatial key                                   |
| `naics_code` |   often   | Join with OSHA Safety, LEHD, and other NAICS-indexed datasets |
| `entity_urn` | sometimes | Entity resolution link (null until resolution pipeline runs)  |

## Example query [#example-query]

Find pioneer restaurants in a target metro area:

```sql
SELECT
  poi_id,
  name,
  category,
  subcategory,
  naics_code,
  walk_score,
  transit_score,
  is_pioneer
FROM read_parquet('poi-intelligence-2026-04.parquet')
WHERE h3_index LIKE '8828308%'
  AND is_pioneer = true
  AND category = 'restaurant'
ORDER BY walk_score DESC;
```

## Known limitations [#known-limitations]

* `reviews_sample` contains at most 5 representative reviews per POI. Full review text is not redistributable.
* `walk_score` and `transit_score` are null for POIs in areas without sufficient data coverage.
* Multi-source resolution means a single real-world business may have been merged from 2–3 source entries. Check `metadata.identifier` for source-native IDs.
* Pioneer classification depends on Urban Signal Grid scoring freshness — newly scored cells may take up to one refresh cycle to propagate.


# Urban Signal Grid schema (/codex/schemas/urban-signal-grid)



The Urban Signal Grid dataset contains \~454K H3 resolution-8 cells across 22 U.S. metros. Each cell is scored across eight signal groups that measure business vitality, population momentum, economic strength, and more. Use it for site selection, territory planning, and predictive analytics.

Every record inherits the full [APRS envelope](/codex/normalization-standard) (`record_id`, `chunk_id`, bitemporal fields, `confidence_score`, `provenance`) and carries the [join keys](/codex/join-keys) documented below.

## Dataset-specific fields [#dataset-specific-fields]

| Field                  | Type             | Nullable | Description                                                                               |
| ---------------------- | ---------------- | :------: | ----------------------------------------------------------------------------------------- |
| `h3_index`             | string           |    no    | H3 resolution-8 cell (\~0.74 km²). Primary key.                                           |
| `metro_slug`           | string           |    no    | Metro area identifier.                                                                    |
| `composite_score`      | numeric \[0,100] |    no    | Weighted aggregate of all eight signal groups.                                            |
| `score_low`            | numeric          |    no    | Lower bound of the 90% confidence interval.                                               |
| `score_high`           | numeric          |    no    | Upper bound of the 90% confidence interval.                                               |
| `confidence`           | float \[0,1]     |    no    | Model confidence in the composite score.                                                  |
| `business_vitality`    | numeric \[0,100] |    no    | New business formation, closure rates, and revenue signals.                               |
| `population_momentum`  | numeric \[0,100] |    no    | Population growth trends and migration inflows.                                           |
| `demographics`         | numeric \[0,100] |    no    | Income distribution, education levels, age cohorts.                                       |
| `economic_strength`    | numeric \[0,100] |    no    | Employment density, wage levels, and sector diversity.                                    |
| `development_pipeline` | numeric \[0,100] |    no    | Active permits, construction starts, and rezoning activity.                               |
| `accessibility`        | numeric \[0,100] |    no    | Transit coverage, walkability, and commute times.                                         |
| `safety_environment`   | numeric \[0,100] |    no    | Crime rates, environmental hazard exposure, and code violations.                          |
| `amenity_demand`       | numeric \[0,100] |    no    | Retail density, restaurant activity, and consumer demand indicators.                      |
| `pioneer_flag`         | boolean          |    no    | `true` when the cell contains POIs that opened in the last 12 months in a growth context. |
| `scored_at`            | timestamptz      |    no    | Timestamp of the scoring run.                                                             |
| `scoring_version`      | string           |    no    | Methodology version (semver).                                                             |

## Signal groups [#signal-groups]

Each signal group is scored from 0 to 100 where higher values indicate stronger performance. The `composite_score` is a weighted combination of all eight groups.

| Signal group           | What it measures                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `business_vitality`    | New business formation rate, closure rate, and revenue signals from POI and licensing data            |
| `population_momentum`  | Population growth trends, net migration inflows, USPS vacancy rates, and Census ACS indicators        |
| `demographics`         | Household income distribution, educational attainment, and age-cohort diversity                       |
| `economic_strength`    | Employment density, median wage, and NAICS sector diversity from LEHD and BLS data                    |
| `development_pipeline` | Active building permits, construction starts, and recent rezoning approvals                           |
| `accessibility`        | Transit stop density, FTA NTD ridership volumes, Walk Score, and average commute time from LEHD flows |
| `safety_environment`   | Reported crime rates, environmental hazards (EPA TRI), and code violation density                     |
| `amenity_demand`       | Retail and restaurant POI density, consumer foot-traffic proxies, and review velocity                 |


  The Urban Signal Grid is cell-based, not parcel-based. Each H3 resolution-8 cell covers approximately 0.74 km². For parcel-level analysis, join with [Permit Signals](/codex/schemas/permit-signals) or [Civic Intelligence](/codex/schemas/civic-intelligence) using `h3_index`.


## Pioneer flag [#pioneer-flag]

The `pioneer_flag` field identifies cells where new points of interest opened in the last 12 months in a growth context — rising composite score, positive net migration, and nearby new construction permits. This flag helps detect early-stage neighborhood transformation before it shows up in traditional indicators.

## Join keys [#join-keys]

| Key          | Presence | Notes                                                  |
| ------------ | :------: | ------------------------------------------------------ |
| `record_id`  |  always  | APRS URN                                               |
| `chunk_id`   |  always  | Deterministic from `record_id`                         |
| `h3_index`   |  always  | Primary spatial key — join with any H3-indexed dataset |
| `metro_slug` |  always  | Metro area identifier                                  |

## Example query [#example-query]

Find the top-scoring cells in a metro area and compare signal group breakdowns:

```sql
SELECT
  h3_index,
  composite_score,
  business_vitality,
  population_momentum,
  development_pipeline,
  accessibility,
  pioneer_flag
FROM read_parquet('urban-signal-grid-2026-04.parquet')
WHERE metro_slug = 'philadelphia-pa'
  AND composite_score >= 75
ORDER BY composite_score DESC
LIMIT 20;
```

## Known limitations [#known-limitations]

* Coverage is limited to 22 U.S. metros. Cells outside covered metros are not scored.
* The grid is cell-grained (H3 resolution 8). Sub-cell variation within a \~0.74 km² area is not captured.
* `pioneer_flag` depends on POI Intelligence freshness — newly opened businesses may take up to 30 days to appear.
* Signal group weights in the `composite_score` are methodology-version-dependent. Compare scores only within the same `scoring_version`.


# Atlassian (Jira & Confluence) (/layer/integrations/atlassian)



The Atlassian integration covers both Jira and Confluence Cloud. Connect one accessible Atlassian Cloud site with one-click OAuth brokered through Auth0 — there's no API token to create or paste. One sign-in connects both products.

## What you'll need [#what-youll-need]

* An Atlassian account with access to the Jira and Confluence data you want Layer to sync.
* Three minutes.


  Atlassian OAuth does not grant extra product permissions. Layer can only collect data the account that authorizes the connection is already allowed to view. The current connection flow supports accounts with exactly one accessible Atlassian Cloud site; site selection for accounts with multiple sites is not available yet.


## Set it up [#set-it-up]


  
    ### Open the Atlassian integration in Layer [#open-the-atlassian-integration-in-layer]

    In Layer, go to **Integrations**, find Atlassian, and click **Connect**.
  

  
    ### Sign in with your Atlassian account [#sign-in-with-your-atlassian-account]

    You'll be redirected to Atlassian's OAuth screen. Sign in with the account that has access to the Jira and Confluence site you want to connect.
  

  
    ### Authorize the requested scopes [#authorize-the-requested-scopes]

    Atlassian will list the requested scopes:

    * `read:jira-work`, `read:jira-user`, `read:project:jira` — read Jira issues, user references, and project metadata
    * `read:board-scope:jira-software`, `read:sprint:jira-software` — read Jira Software boards and sprints
    * `read:servicedesk-request` — read Jira Service Management requests visible to the connecting account
    * `read:confluence-content.summary`, `read:confluence-space.summary`, `read:confluence-user` — read Confluence pages, spaces, and user references
    * `read:me` — identify the connecting account
    * `offline_access` — refresh the connection without asking you to sign in for every sync

    Click **Accept**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync resolves the site's `cloud_id` and collects the supported Jira and Confluence objects visible to the connecting account.
  


## What gets synced [#what-gets-synced]

| Object                  | Data collected                                                                                                   |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Jira site and projects  | Site identity plus project names, keys, and relationships                                                        |
| Jira issues             | Summary, status, priority, type, assignee and reporter references, project, and timestamps                       |
| Jira Software           | Boards and their active, future, and closed sprints                                                              |
| Jira Service Management | Asset-, hardware-, software-, access-, equipment-, and device-related requests visible to the connecting account |
| Confluence              | Site, spaces, pages, owners, status, version, and parent relationships                                           |

The current connection does not enumerate Atlassian groups or provide a complete organization user directory. User references are collected only when they appear on supported Jira or Confluence objects.

## Token refresh [#token-refresh]

Layer uses the refresh token granted by `offline_access` before syncs, so the connection can stay active without manual re-authorization. If Atlassian rejects a refresh — for example, because access was revoked — the connection status changes to **needs re-auth** and you can reconnect with one click.

## Troubleshooting [#troubleshooting]


  
    The OAuth token inherits the connecting account's Jira permissions. Confirm that account can browse the affected projects, users, boards, sprints, or service-management requests in Atlassian, then sync again.
  

  
    Confluence must be available on the same Atlassian Cloud site, and the connecting account must be allowed to view its spaces and pages. Check the account's access in Atlassian, then reconnect if its permissions changed.
  



# AWS (/layer/integrations/aws)



The AWS integration discovers IAM users, S3 buckets, and your account identity via STS. Use it to maintain a complete cloud infrastructure inventory and generate compliance evidence for access-control and asset-management controls in [Axiom Codex](/codex).

## What you'll need [#what-youll-need]

* AWS account with permission to create an IAM user (or IAM role for cross-account access).
* Three minutes.

## Set it up [#set-it-up]


  
    ### Create an IAM user in AWS [#create-an-iam-user-in-aws]

    In the AWS Console, go to **IAM → Users → Add users**.

    * Name: `axiom-layer-readonly`
    * Access type: **Programmatic access**

    On the permissions step, attach the AWS-managed policy **`ReadOnlyAccess`** (or use the trimmed policy below if you want least privilege).
  

  
    ### Save the access key [#save-the-access-key]

    On the final step, copy the **Access key ID** and **Secret access key**. The secret is only shown once.
  

  
    ### Paste into Layer [#paste-into-layer]

    In Layer, go to **Integrations**, find AWS, and click **Connect**. Paste the Access Key ID, Secret Access Key, and your default region (e.g. `us-east-1`). Click **Connect**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync pulls your account identity, IAM users, and S3 bucket inventory. Typically finishes in under 10 minutes.
  


## Least-privilege policy [#least-privilege-policy]

If you don't want to grant `ReadOnlyAccess`, attach this trimmed policy instead:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity",
        "iam:ListUsers",
        "s3:ListAllMyBuckets"
      ],
      "Resource": "*"
    }
  ]
}
```

## What gets synced [#what-gets-synced]

| Object           | Fields             | Refresh cadence |
| ---------------- | ------------------ | --------------- |
| Account identity | account ID, region | Daily           |
| IAM users        | username           | Daily           |
| S3 buckets       | bucket name        | Daily           |

## Compliance evidence [#compliance-evidence]

AWS data generates evidence records for the following SOC 2 controls:

| Evidence            | Controls            |
| ------------------- | ------------------- |
| IAM user inventory  | CC6.1, CC6.2, CC6.3 |
| S3 bucket inventory | CC6.6, CC6.7        |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Troubleshooting [#troubleshooting]


  
    Verify the IAM user has the permissions listed in the least-privilege policy above. If you're using a more restrictive policy, confirm that `sts:GetCallerIdentity`, `iam:ListUsers`, and `s3:ListAllMyBuckets` are all allowed.
  

  
    Cross-account role support is on the roadmap. Email [support@axiomancer.io](mailto:support@axiomancer.io) to be notified when it ships.
  



# Azure (/layer/integrations/azure)



The Azure integration discovers subscriptions, resource groups, and RBAC role assignments across your Azure environment. Use it to maintain a cloud infrastructure inventory and generate compliance evidence for access-control and asset-management controls in [Axiom Codex](/codex).

## What you'll need [#what-youll-need]

* An Azure subscription.
* Permission to create an app registration in Microsoft Entra ID (Azure AD).
* Five minutes.

## Set it up [#set-it-up]


  
    ### Register an app in Azure [#register-an-app-in-azure]

    In the Azure portal, go to **Microsoft Entra ID → App registrations → New registration**.

    * Name: `Axiom Layer — Azure`
    * Supported account types: **Single tenant**

    After creation, copy the **Application (client) ID** and **Directory (tenant) ID** from the overview page.
  

  
    ### Create a client secret [#create-a-client-secret]

    Go to **Certificates & secrets → New client secret**. Copy the secret value — you won't be able to see it again.
  

  
    ### Assign the Reader role on your subscription [#assign-the-reader-role-on-your-subscription]

    Go to **Subscriptions → (your subscription) → Access control (IAM) → Add role assignment**.

    * Role: **Reader**
    * Assign access to: **Application**
    * Select the `Axiom Layer — Azure` app you just created

    Also copy the **Subscription ID** from the subscription overview page.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations**, find Azure, and click **Connect**. Enter:

    * **Subscription ID**
    * **Client ID** (Application ID)
    * **Client Secret**
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in under 10 minutes.
  


## What gets synced [#what-gets-synced]

| Object                | Fields                     | Refresh cadence |
| --------------------- | -------------------------- | --------------- |
| Subscription          | subscription ID, tenant ID | Daily           |
| Resource groups       | name, location, tags       | Daily           |
| RBAC role assignments | principal, role, scope     | Daily           |

Layer also emits a **HostedOn** relationship from every discovered resource group to its parent subscription, with the resource group's `location` stored as relationship metadata. The result is a connected view of how each Azure resource group rolls up to the subscription that owns it — useful when scoping [access reviews](/layer/access-reviews) to a specific subscription, tracing role-assignment blast radius down the hierarchy, and feeding subscription-level evidence in [Axiom Codex](/codex).

## Compliance evidence [#compliance-evidence]

Azure data generates evidence records for the following SOC 2 controls:

| Evidence                 | Controls            |
| ------------------------ | ------------------- |
| RBAC role assignments    | CC6.1, CC6.2, CC6.3 |
| Resource group inventory | CC6.6, CC6.7        |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Least-privilege permissions [#least-privilege-permissions]

The **Reader** role on the subscription is sufficient for all synced data. If you want to scope access more narrowly, create a custom role with these permissions:

```json
{
  "Name": "Axiom Layer Read",
  "Actions": [
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Authorization/roleAssignments/read"
  ],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}
```

## Troubleshooting [#troubleshooting]


  
    Verify the Tenant ID, Client ID, and Client Secret are correct. If the client secret expired, generate a new one in **Certificates & secrets** and update it in Layer.
  

  
    Confirm the app registration has the **Reader** role (or equivalent) assigned on the target subscription. Role assignments can take a few minutes to propagate after creation.
  

  
    Create a separate connection for each subscription. Each connection requires its own Subscription ID but can share the same app registration if you assign the Reader role on each subscription.
  



# CrowdStrike Falcon (/layer/integrations/crowdstrike)



The CrowdStrike Falcon integration syncs your managed device inventory, open detections, and prevention policy configuration. Use it to maintain a complete device inventory, track endpoint security posture, and generate compliance evidence for [Axiom Codex](/codex).

## What you'll need [#what-youll-need]

* CrowdStrike Falcon console access with permission to create API clients.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Create an API client in CrowdStrike [#create-an-api-client-in-crowdstrike]

    In the Falcon console, go to **Support and resources → API clients and keys** and click **Create API client**.

    * Name: `Axiom Layer`
    * Scopes: enable **Read** for **Hosts**, **Detections**, and **Prevention Policies**

    Copy the **Client ID** and **Client Secret**. The secret is only shown once.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations**, find CrowdStrike, and click **Connect**. Paste the **Client ID** and **Client Secret**, then click **Connect**.

    
      If your CrowdStrike tenant uses a non-default regional API endpoint (for example `https://api.us-2.crowdstrike.com`), enter it in the **Base URL** field. Leave it blank for the default US-1 endpoint.
    
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately. Fleets under 5,000 devices typically finish in under 10 minutes.
  


## What gets synced [#what-gets-synced]

| Object              | Fields                                                                                            | Refresh cadence |
| ------------------- | ------------------------------------------------------------------------------------------------- | --------------- |
| Devices             | hostname, device ID, platform (Windows/macOS/Linux), OS version, serial number, last seen, status | Daily           |
| Detections          | detection ID, status (new/in-progress/resolved)                                                   | Daily           |
| Prevention policies | policy ID, policy count                                                                           | Daily           |

## Compliance evidence [#compliance-evidence]

CrowdStrike data generates evidence records for the following SOC 2 controls:

| Evidence                                      | Controls     |
| --------------------------------------------- | ------------ |
| Device inventory with OS and status breakdown | CC6.1, CC6.7 |
| Open detections count                         | CC7.2, CC7.3 |
| Prevention policy inventory                   | CC6.1, CC6.7 |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Troubleshooting [#troubleshooting]


  
    Double-check that you copied the Client ID and Client Secret correctly. If the secret was rotated or the API client was disabled, create a new one in the Falcon console.
  

  
    Verify the API client has the **Hosts → Read** scope enabled. Also confirm your CrowdStrike tenant has devices enrolled — a newly created tenant with no sensor deployments will return an empty inventory.
  

  
    Enter your regional API base URL when connecting (for example `https://api.eu-1.crowdstrike.com` for EU). If you connected without specifying a base URL, disconnect and reconnect with the correct endpoint.
  



# Datadog (/layer/integrations/datadog)



The Datadog integration pulls monitors, downtime windows, and log index configurations from your Datadog account. This data feeds compliance evidence for availability and incident-response controls in [Axiom Codex](/codex).

## What you'll need [#what-youll-need]

* A Datadog account with permission to create API and application keys.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Create an API key [#create-an-api-key]

    In Datadog, go to **Organization Settings → API Keys** and click **New Key**. Name it `Axiom Layer` and copy the key value.
  

  
    ### Create an application key [#create-an-application-key]

    Go to **Organization Settings → Application Keys** and click **New Key**. Name it `Axiom Layer` and copy the key value.
  

  
    ### Paste both keys into Layer [#paste-both-keys-into-layer]

    In Layer, go to **Integrations**, find Datadog, and click **Connect**. Paste the **API Key** and **Application Key**, then click **Connect**.

    
      If your Datadog account uses a regional site (for example `api.datadoghq.eu` or `api.us5.datadoghq.com`), enter the site hostname in the **Site** field. Leave it blank for the default US1 site.
    
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in under five minutes.
  


## What gets synced [#what-gets-synced]

| Object      | Fields                            | Refresh cadence |
| ----------- | --------------------------------- | --------------- |
| Monitors    | name, type, status, tags          | Daily           |
| Downtimes   | scope, start/end, active status   | Daily           |
| Log indexes | name, retention days, daily limit | Daily           |

## Compliance evidence [#compliance-evidence]

Datadog data generates evidence records for the following SOC 2 controls:

| Evidence                            | Controls     |
| ----------------------------------- | ------------ |
| Monitor uptime and SLA posture      | CC7.2, A1.2  |
| Downtime and alert policy inventory | CC7.2, CC7.3 |
| Log index retention settings        | CC7.2, CC6.1 |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Required permissions [#required-permissions]

The API key authenticates requests to Datadog's API. The application key determines the scope of data your requests can access — it inherits the permissions of the Datadog user who created it. A user with the **Datadog Read Only** role is sufficient.

## Troubleshooting [#troubleshooting]


  
    The application key may belong to a user without read permissions. Create the application key from a user account that has at least the **Datadog Read Only** role.
  

  
    Verify that your Datadog account has monitors configured and that the API key belongs to the correct organization. If you have multiple Datadog organizations, make sure you're generating keys in the right one.
  

  
    Enter your regional site hostname (for example `api.datadoghq.eu`) when connecting. If you connected without specifying a site, disconnect and reconnect with the correct hostname.
  



# Google Cloud (/layer/integrations/gcp)



The Google Cloud integration discovers IAM policy bindings and collects Cloud Audit Log summaries for a GCP project. Use it to track who has access to your cloud resources and generate compliance evidence for identity and monitoring controls in [Axiom Codex](/codex).

## What you'll need [#what-youll-need]

* A GCP project with Cloud Resource Manager and Cloud Logging APIs enabled.
* Permission to create a service account in the project.
* Five minutes.

## Set it up [#set-it-up]


  
    ### Create a service account [#create-a-service-account]

    In the Google Cloud Console, go to **IAM & Admin → Service Accounts** and click **Create Service Account**.

    * Name: `axiom-layer-readonly`
    * Role: **Viewer** (or a custom role — see below)
  

  
    ### Create and download a key [#create-and-download-a-key]

    Click on the service account, go to **Keys → Add Key → Create New Key**, and choose **JSON**. A JSON key file downloads automatically — keep it safe.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations**, find Google Cloud, and click **Connect**. Enter your **Project ID** and paste the full contents of the JSON key file into the **Service Account Key** field. Click **Connect**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in under five minutes.
  


## What gets synced [#what-gets-synced]

| Object                            | Fields                            | Refresh cadence |
| --------------------------------- | --------------------------------- | --------------- |
| IAM policy bindings               | role, members, binding count      | Daily           |
| Cloud Audit Logs (30-day summary) | entry count, breakdown by service | Daily           |

## Compliance evidence [#compliance-evidence]

GCP data generates evidence records for the following SOC 2 controls:

| Evidence                    | Controls            |
| --------------------------- | ------------------- |
| Project IAM policy bindings | CC6.1, CC6.2, CC6.3 |
| Cloud Audit Logs summary    | CC7.1, CC7.2        |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Least-privilege permissions [#least-privilege-permissions]

The **Viewer** role is sufficient. If you prefer a custom role with narrower scope, include these permissions:

* `resourcemanager.projects.getIamPolicy`
* `logging.logEntries.list`
* `logging.logs.list`

## Troubleshooting [#troubleshooting]


  
    Verify the service account key JSON is complete (it should start with `{` and end with `}`). If the key was deleted or the service account disabled, create a new key and update it in Layer.
  

  
    Cloud Audit Logs must be enabled for the project. Go to **IAM & Admin → Audit Logs** in the Cloud Console and confirm that admin activity and data access logs are turned on for the services you want to monitor.
  

  
    Create a separate connection for each project. You can reuse the same service account if you grant it the Viewer role on each additional project.
  



# GitHub (/layer/integrations/github)



The GitHub integration discovers your organization's repositories, members, and Copilot seat utilization — essential for access review, license optimization, and SOC 2 evidence.

## What you'll need [#what-youll-need]

* GitHub **Organization Owner** role on the org you want to connect.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the GitHub integration in Layer [#open-the-github-integration-in-layer]

    In Layer, go to **Integrations**, find GitHub, and click **Connect**.
  

  
    ### Install the Axiom GitHub App [#install-the-axiom-github-app]

    You'll be redirected to GitHub. Choose the organization to install on, then pick **All repositories** (recommended for full inventory) or specific repos.
  

  
    ### Approve the requested permissions [#approve-the-requested-permissions]

    The Axiom GitHub App requests **read-only** access to:

    * **Repository**: Metadata, Contents, Issues, Pull requests
    * **Organization**: Members, Administration, Copilot

    Click **Install**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately. Larger orgs (1,000+ members) may take 15–20 minutes.
  


## What gets synced [#what-gets-synced]

| Object                | Fields                                                                       | Refresh cadence |
| --------------------- | ---------------------------------------------------------------------------- | --------------- |
| Organizations         | login, type                                                                  | Every 6 hours   |
| Repositories          | name, full name, visibility (public/private/internal), default branch, owner | Every 6 hours   |
| Teams                 | name, slug, privacy, member count, repo count                                | Every 6 hours   |
| Team membership       | user → team links                                                            | Every 6 hours   |
| Repository governance | repo → team links with team permission                                       | Every 6 hours   |
| Copilot seats         | total seats provisioned per organization                                     | Daily           |

## Teams, members, and repository governance [#teams-members-and-repository-governance]

Layer enumerates every team in each connected GitHub organization and emits a **Team** asset for each one, along with two relationship types that map who has access to what:

* **MemberOf** — links every team member (a Layer user keyed by GitHub login) to the team they belong to.
* **GovernedBy** — links every repository the team is granted access to back to the team, with the team's permission level (`pull`, `push`, `admin`, etc.) stored on the relationship.

Together these surface the real GitHub access path — *which engineers are on which teams, and which repos those teams govern* — so [access reviews](/layer/access-reviews) and [offboarding](/layer/offboarding) can deprovision team-derived repo access without manually tracing org-wide permissions. Pagination is followed automatically, so orgs with hundreds of teams sync completely.

Private (secret) teams are still discovered as long as the Axiom GitHub App is installed at the organization level with **Members: Read** granted.

## Copilot seat utilization [#copilot-seat-utilization]

Layer automatically checks each connected organization for GitHub Copilot seat data. If your organization has a Copilot Business or Enterprise plan, the total number of provisioned seats appears in your asset inventory and feeds compliance evidence. Organizations without Copilot are skipped silently.

## Compliance evidence [#compliance-evidence]

GitHub data generates evidence records for the following SOC 2 controls:

| Evidence                                      | Controls     |
| --------------------------------------------- | ------------ |
| Repository inventory and visibility breakdown | CC8.1        |
| Organization governance                       | CC8.1        |
| Team membership and repository governance     | CC6.1, CC6.3 |
| Copilot seat utilization                      | CC7.2        |

See the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for full control descriptions.

## Why GitHub App, not OAuth or PAT [#why-github-app-not-oauth-or-pat]

GitHub Apps issue **fine-grained, expiring tokens** scoped to the specific resources you authorized. Personal Access Tokens (the old way) grant a single user's full account access until manually revoked — much worse for least-privilege.

## Troubleshooting [#troubleshooting]


  
    Re-check that you installed on the **organization**, not your personal account. Reinstall via [github.com/settings/installations](https://github.com/settings/installations) and pick the org.
  

  
    The Axiom GitHub App needs **Organization → Members: Read** to enumerate team members and **Repository → Metadata: Read** to enumerate team-governed repositories. Both are requested by default during install — if the install was customized to a narrower scope, reinstall via [github.com/settings/installations](https://github.com/settings/installations) and accept the full permission set.
  

  
    Copilot seat data requires a Copilot Business or Enterprise subscription on the organization. If your org uses individual Copilot plans, seat counts aren't available through the organization API.
  

  
    Go to **Integrations → GitHub → Disconnect** in Layer, then uninstall the Axiom app from [github.com/organizations/YOUR\_ORG/settings/installations](https://github.com).
  



# Google Workspace (/layer/integrations/google-workspace)



The Google Workspace integration syncs users, groups, and OAuth app activity. No Google Cloud project required — the connecting super-admin signs in once and grants admin consent.

## What you'll need [#what-youll-need]

* Google Workspace **Super Admin** role (or a custom admin role with Reports and Directory read access).
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the Google Workspace integration in Layer [#open-the-google-workspace-integration-in-layer]

    In Layer, go to **Integrations**, find Google Workspace, and click **Connect**.
  

  
    ### Sign in with your super-admin account [#sign-in-with-your-super-admin-account]

    You'll be redirected to Google's sign-in screen. Use the super-admin account for the Workspace tenant you want to connect.
  

  
    ### Grant admin consent [#grant-admin-consent]

    Google will show the requested scopes and ask for admin consent on behalf of the entire tenant. Click **Allow**.

    Scopes requested:

    * `admin.directory.user.readonly` — list users
    * `admin.directory.group.readonly` — list groups and membership
    * `admin.reports.audit.readonly` — read audit logs to discover OAuth app installs
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in 10–30 minutes depending on directory size.
  


## What gets synced [#what-gets-synced]

| Object                           | Fields                                                  | Refresh cadence |
| -------------------------------- | ------------------------------------------------------- | --------------- |
| Users                            | name, email, suspended state, last login                | Every 6 hours   |
| Groups                           | name, description, member emails                        | Every 6 hours   |
| OAuth app grants                 | app name, scopes, granting users, install date          | Daily           |
| OAuth app **Uses** relationships | per-user → app links with the scopes each user approved | Daily           |

## Token refresh [#token-refresh]

Google access tokens expire approximately one hour after they are issued. Layer automatically refreshes tokens in the background each time a sync runs, so your connection stays active without any manual re-authorization. If a refresh fails — for example, because the admin revoked access in the Google Admin console — the connection status changes to **needs re-auth** and you can reconnect with one click.

## Troubleshooting [#troubleshooting]


  
    Only Super Admins (or admins with the Reports and Directory roles) can grant the consent this integration needs. Sign in with a super-admin account.
  

  
    This means Layer could not refresh the access token automatically. The most common cause is a revoked grant. Go to **Integrations → Google Workspace** and click **Reconnect** to re-authorize.
  

  
    Go to **Integrations → Google Workspace → Disconnect** in Layer. To fully revoke, also remove Axiom from your tenant at [admin.google.com/ac/owl/list?tab=apps](https://admin.google.com/ac/owl/list?tab=apps).
  



# Microsoft Intune (/layer/integrations/intune)



The Microsoft Intune integration syncs your managed device fleet — laptops, phones, and tablets — along with compliance policies and conditional access rules. Use it to track device health, encryption status, and OS versions across your organization.

## What you'll need [#what-youll-need]

* A Microsoft 365 tenant with Intune licenses assigned.
* **Global Administrator** (or Intune Administrator) role to grant admin consent.
* Two minutes.

## Set it up [#set-it-up]

### Option A — one-click OAuth (recommended) [#option-a--one-click-oauth-recommended]


  
    ### Open the Intune integration in Layer [#open-the-intune-integration-in-layer]

    In Layer, go to **Integrations**, find Microsoft Intune, and click **Connect**.
  

  
    ### Sign in and grant consent [#sign-in-and-grant-consent]

    You'll be redirected to Microsoft's sign-in screen. Use a Global Admin or Intune Admin account and tick **Consent on behalf of your organization**, then click **Accept**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in 10–20 minutes depending on fleet size.
  


### Option B — manual credentials [#option-b--manual-credentials]

Use this method if your organization requires a dedicated app registration instead of delegated OAuth.


  
    ### Register an app in Azure [#register-an-app-in-azure]

    In the Azure portal, go to **App registrations → New registration**.

    * Name: `Axiom Layer — Intune`
    * Supported account types: **Single tenant**

    After creation, copy the **Application (client) ID** and **Directory (tenant) ID** from the overview page.
  

  
    ### Create a client secret [#create-a-client-secret]

    Go to **Certificates & secrets → New client secret**. Copy the secret value — you won't be able to see it again.
  

  
    ### Grant API permissions [#grant-api-permissions]

    Go to **API permissions → Add a permission → Microsoft Graph → Application permissions** and add:

    * `DeviceManagementManagedDevices.Read.All` — read managed devices
    * `DeviceManagementConfiguration.Read.All` — read compliance and configuration policies
    * `Policy.Read.All` — read conditional access policies

    Click **Grant admin consent** for your tenant.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations → Microsoft Intune → Connect** and enter:

    * **Tenant ID**
    * **Client ID**
    * **Client Secret**
  

  
    ### Wait for the first sync [#wait-for-the-first-sync-1]

    The first sync pulls devices, compliance policies, and conditional access policies. Typically finishes in 10–20 minutes.
  


## What gets synced [#what-gets-synced]

| Object                      | Fields                                                                                                       | Refresh cadence |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------- |
| Managed devices             | name, serial number, model, OS, OS version, compliance state, encryption state, assigned user, last check-in | Every 6 hours   |
| Compliance policies         | name, platforms, last modified date                                                                          | Every 6 hours   |
| Conditional access policies | name, state (enabled/disabled), created and modified dates                                                   | Every 6 hours   |

## Token refresh [#token-refresh]

When you connect via OAuth, Microsoft access tokens expire approximately one hour after they are issued. Layer automatically refreshes tokens in the background each time a sync runs, so your connection stays active without any manual re-authorization. If a refresh fails — for example, because an admin revoked consent in the Azure portal — the connection status changes to **needs re-auth** and you can reconnect with one click.

## Use cases [#use-cases]

* **Device inventory** — see every managed laptop, phone, and tablet in one place, with model, OS, and assigned user.
* **Compliance monitoring** — check which devices are compliant, non-compliant, or not evaluated, and track encryption status.
* **Offboarding** — identify devices assigned to departing employees so you can wipe or reassign them.
* **Audit evidence** — Intune data feeds into [Axiom Codex](/codex) as evidence for SOC 2 and ISO 27001 device-management controls.

## Troubleshooting [#troubleshooting]


  
    This means Layer could not refresh the access token automatically. The most common cause is revoked consent or an expired client secret. Go to **Integrations → Microsoft Intune** and click **Reconnect** to re-authorize.
  

  
    Verify that Intune licenses are assigned to users in your tenant and that devices are enrolled. If you used manual credentials, confirm the app registration has the correct API permissions and that admin consent was granted.
  

  
    Devices that haven't checked in recently or don't have a compliance policy assigned will show as "not evaluated." Assign a compliance policy in the Intune admin center and wait for the next device check-in.
  

  
    Go to **Integrations → Microsoft Intune → Disconnect** in Layer. If you used OAuth, also remove the Axiom app from **Enterprise Applications** in the Azure portal. If you used manual credentials, delete or disable the app registration.
  



# Jamf Pro (/layer/integrations/jamf)



The Jamf Pro integration covers your managed Mac, iPhone, and iPad fleet.

## What you'll need [#what-youll-need]

* Jamf Pro **administrator** role with permission to create API roles and clients.
* Your Jamf Pro URL (e.g. `https://yourorg.jamfcloud.com`).
* Five minutes.

## Set it up [#set-it-up]


  
    ### Create an API role in Jamf Pro [#create-an-api-role-in-jamf-pro]

    In Jamf Pro, go to **Settings → System → API roles and clients → API Roles → + New**.

    * Display name: `Axiom Reader`
    * Privileges: `Read Computers`, `Read Mobile Devices`, `Read Users`, `Read Groups`, `Read Computer Inventory Collection Settings`

    Save.
  

  
    ### Create an API client [#create-an-api-client]

    Go to **API Clients → + New**.

    * Display name: `Axiom`
    * API roles: select `Axiom Reader`
    * Access Token Lifetime: 30 minutes (default)
    * Authorization Type: **API Client**

    Save and copy the **Client ID** and **Client Secret** that Jamf displays.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations**, find Jamf Pro, click **Connect**, and paste:

    * Jamf Pro URL
    * Client ID
    * Client Secret
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The first sync mints a short-lived token, pulls devices and users, and typically finishes in 10-20 minutes.
  


## What gets synced [#what-gets-synced]

| Object         | Fields                                                        | Refresh cadence |
| -------------- | ------------------------------------------------------------- | --------------- |
| Computers      | name, serial number, OS version, last check-in, assigned user | Every 6 hours   |
| Mobile devices | name, serial, OS, model, owner                                | Every 6 hours   |
| Users          | username, email, full name                                    | Daily           |
| Smart groups   | name, criteria, member count                                  | Daily           |

## Why client credentials, not OAuth [#why-client-credentials-not-oauth]

Jamf's OAuth model is per-tenant — each customer's Jamf URL is the issuer, so a single multi-tenant OAuth app doesn't apply. The API Client pattern is what Jamf recommends for service-to-service integrations.

## Troubleshooting [#troubleshooting]


  
    Tokens are short-lived (30 min default). Layer mints a new one for each sync, but if you rotated the Client Secret in Jamf, paste the new value into Layer.
  

  
    Check the API role privileges — `Read Computers` and `Read Mobile Devices` are separate. Both must be granted.
  



# JumpCloud (/layer/integrations/jumpcloud)



The JumpCloud integration syncs users, groups, group memberships, and the SaaS apps your team actually signs into via JumpCloud SSO — the foundation of license true-up and offboarding workflows in Layer.

## What you'll need [#what-youll-need]

* JumpCloud **Administrator** access.
* The ability to create an API key in your JumpCloud tenant.
* Three minutes.

## Set it up [#set-it-up]


  
    ### Create an API key in JumpCloud [#create-an-api-key-in-jumpcloud]

    In the JumpCloud Admin Console, click your initials in the top right and choose **My API Key**. Click **Generate New API Key** and copy the value — you won't be able to see it again.
  

  
    ### Paste it into Layer [#paste-it-into-layer]

    In Layer, go to **Integrations**, find JumpCloud, and click **Connect**. Paste your API key, then click **Connect**.

    The default JumpCloud API base URL is `https://console.jumpcloud.com/api`. Override it only if your tenant uses a custom region.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately. Most tenants finish in under 15 minutes.
  


## What gets synced [#what-gets-synced]

| Object               | Fields                                     | Refresh cadence |
| -------------------- | ------------------------------------------ | --------------- |
| Users                | username, email, status, department, title | Every 6 hours   |
| Groups               | name, description, member count            | Every 6 hours   |
| Group memberships    | user → group links                         | Every 6 hours   |
| SaaS apps (from SSO) | app name, event count                      | Every 6 hours   |
| App usage            | user → app links with last SSO timestamp   | Every 6 hours   |

### SaaS apps from SSO events [#saas-apps-from-sso-events]

Layer reads the last 30 days of JumpCloud SSO events from the Insights API and creates one **SaaS app** asset per distinct application your users signed into. No additional API calls or integrations are required — the apps appear automatically once you connect JumpCloud.

For every successful SSO event, Layer also creates a **Uses** relationship from the user to the app, keeping the most recent sign-in timestamp as `last_sso` metadata. Duplicate sign-ins are deduplicated to one edge per user → app pair, so the graph stays clean even for power users.

These edges are what powers license true-up and offboarding checks against your JumpCloud-managed SaaS apps. The SaaS app assets are tagged with `source: sso_events` and a confidence of `0.75` — they're signal-derived, so they may not exactly match the SSO connector list configured in JumpCloud.

### Group memberships [#group-memberships]

For every JumpCloud user group, Layer fetches the member list from `/v2/usergroups/{id}/members` and creates a **MemberOf** relationship from each user to the group. If your API key doesn't have scope to read group members, Layer skips this step without failing the sync — users and groups still sync as separate assets.

## Required key permissions [#required-key-permissions]

A standard JumpCloud Administrator API key is sufficient. Layer reads from:

* `/systemusers` — user directory
* `/v2/usergroups` and `/v2/usergroups/{id}/members` — groups and memberships
* `/insights/directory/v1/events?service=sso` — last 30 days of SSO events

Layer never writes to your JumpCloud tenant.

## Troubleshooting [#troubleshooting]


  
    The API key may have been rotated or copied incorrectly. Generate a new one in **My API Key** and re-enter it in Layer.
  

  
    SaaS apps are derived from the last 30 days of SSO events. If your tenant hasn't logged any SSO sign-ins in that window, or if the Insights API isn't enabled on your plan, no apps will appear. Users and groups still sync normally.
  

  
    The `/v2/usergroups/{id}/members` endpoint requires the API key to have read access to user groups. Layer treats this call as non-fatal — the rest of the sync completes even when memberships can't be fetched.
  



# Microsoft 365 (/layer/integrations/microsoft-365)



The Microsoft 365 integration syncs users, groups, registered devices, and audit logs. No Azure AD app registration required — the connecting Global Admin signs in once and grants tenant-wide consent.

## What you'll need [#what-youll-need]

* Microsoft 365 **Global Administrator** role (or Privileged Role Admin who can grant tenant-wide consent).
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the Microsoft 365 integration in Layer [#open-the-microsoft-365-integration-in-layer]

    In Layer, go to **Integrations**, find Microsoft 365, and click **Connect**.
  

  
    ### Sign in with your Global Admin account [#sign-in-with-your-global-admin-account]

    You'll be redirected to Microsoft's sign-in. Use the Global Admin account for the tenant you want to connect.
  

  
    ### Grant tenant-wide admin consent [#grant-tenant-wide-admin-consent]

    Microsoft will show the requested scopes. Tick **Consent on behalf of your organization** and click **Accept**.

    Scopes requested:

    * `User.Read.All` — list users
    * `Group.Read.All` — list groups and membership
    * `Directory.Read.All` — read directory metadata
    * `AuditLog.Read.All` — read sign-in and audit logs
    * `Application.Read.All` — list registered apps and service principals
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately and typically finishes in 10–30 minutes depending on directory size.
  


## What gets synced [#what-gets-synced]

| Object            | Fields                                           | Refresh cadence |
| ----------------- | ------------------------------------------------ | --------------- |
| Users             | UPN, display name, account enabled, last sign-in | Every 6 hours   |
| Groups            | name, type, member UPNs                          | Every 6 hours   |
| Devices           | name, OS, compliance state, owner                | Every 6 hours   |
| App registrations | name, scopes granted, sign-ins last 30 days      | Daily           |

## Token refresh [#token-refresh]

Microsoft delegated access tokens expire approximately one hour after they are issued. Layer automatically refreshes tokens in the background each time a sync runs, so your connection stays active without any manual re-authorization. If a refresh fails — for example, because an admin revoked consent in the Azure portal — the connection status changes to **needs re-auth** and you can reconnect with one click.

## Troubleshooting [#troubleshooting]


  
    Only Global Admins can grant tenant-wide consent. Sign in with a Global Admin account, or have one approve the consent request from the Azure portal.
  

  
    This means Layer could not refresh the access token automatically. The most common cause is revoked consent or a changed conditional-access policy. Go to **Integrations → Microsoft 365** and click **Reconnect** to re-authorize.
  

  
    Go to **Integrations → Microsoft 365 → Disconnect** in Layer. To fully revoke, also remove the Axiom app from **Enterprise Applications** in the Azure portal.
  



# Microsoft Teams (/layer/integrations/microsoft-teams)



The Microsoft Teams integration syncs every team in your tenant, the unique members across those teams, and a 30-day activity report so you can see which users actually use Teams. It's the companion to [Microsoft 365](/layer/integrations/microsoft-365) — connect both for full coverage of the directory and the collaboration surface.

## What you'll need [#what-youll-need]

* Microsoft 365 **Teams Administrator** or **Global Administrator** role.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the Microsoft Teams integration in Layer [#open-the-microsoft-teams-integration-in-layer]

    In Layer, go to **Integrations**, find Microsoft Teams, and click **Connect**.
  

  
    ### Sign in with your admin account [#sign-in-with-your-admin-account]

    You'll be redirected to Microsoft's sign-in. Use a Teams Administrator or Global Admin account for the tenant you want to connect.
  

  
    ### Grant tenant-wide admin consent [#grant-tenant-wide-admin-consent]

    Microsoft will list the requested scopes. Tick **Consent on behalf of your organization** and click **Accept**.

    Scopes requested:

    * `Team.ReadBasic.All` — list every team in the tenant
    * `Channel.ReadBasic.All` — read channel metadata
    * `TeamMember.Read.All` — read team membership
    * `TeamSettings.Read.All` — read team configuration
    * `Reports.Read.All` — read Teams user activity reports (last sign-in per user)
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync enumerates all teams, deduplicates members across them, and pulls the 30-day activity report. Typically finishes in 5–15 minutes.
  


## What gets synced [#what-gets-synced]

| Object              | Fields                                                      | Refresh cadence |
| ------------------- | ----------------------------------------------------------- | --------------- |
| Teams               | id, display name, visibility                                | Every 6 hours   |
| Members             | email, display name, Microsoft user ID, last Teams activity | Every 6 hours   |
| Microsoft Teams app | One SaaS asset emitted to the **Apps** view                 | Every 6 hours   |

Members are deduplicated by email across all teams, so a user who sits in 12 teams shows up once in your **People** view. The `last_active_teams` field on each user reflects the most recent activity date from the Teams user activity report (`D30` window) when `Reports.Read.All` is granted.

## Activity report [#activity-report]

If `Reports.Read.All` consent was granted, Layer pulls the **Teams user activity user detail** report and records the last activity date per user (UPN). When the scope is missing — for example, on tenants where Reports has been deliberately scoped down — the connector skips the activity call silently and members are still emitted without a `last_active_teams` value. The connection stays healthy in either case.

## Token refresh [#token-refresh]

Microsoft delegated access tokens expire approximately one hour after they are issued. Layer automatically refreshes tokens in the background each time a sync runs, so your connection stays active without any manual re-authorization. If a refresh fails — for example, because an admin revoked consent in the Azure portal — the connection status changes to **needs re-auth** and you can reconnect with one click.

## Troubleshooting [#troubleshooting]


  
    The connector silently skips the activity report when `Reports.Read.All` is not granted. Reconnect from **Integrations → Microsoft Teams** and approve the full scope set on the consent screen.
  

  
    Private teams require explicit membership for the consenting admin or tenant-wide read consent. Confirm `Team.ReadBasic.All` was approved at the tenant level rather than for a single user.
  

  
    Go to **Integrations → Microsoft Teams → Disconnect** in Layer. To fully revoke, also remove the Axiom app from **Enterprise Applications** in the Azure portal.
  



# Notion (/layer/integrations/notion)



The Notion integration discovers your Notion workspace and its members so they show up in Layer's identity graph alongside the rest of your SaaS. New connections use a one-click OAuth flow — there's no integration token to create or paste.

## What you'll need [#what-youll-need]

* Notion workspace **Owner** role.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the Notion integration in Layer [#open-the-notion-integration-in-layer]

    In Layer, go to **Integrations**, find Notion, and click **Connect**.
  

  
    ### Pick the workspace to connect [#pick-the-workspace-to-connect]

    You'll be redirected to Notion's OAuth screen. If you have access to multiple Notion workspaces, pick the one you want Axiom to inventory.
  

  
    ### Select pages to share with Axiom [#select-pages-to-share-with-axiom]

    Notion asks which pages the integration should see. Selecting **All pages** gives the broadest visibility; selecting individual pages narrows the scope. Member discovery works either way.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    You'll land back at **Integrations** with the Notion card marked connected. The initial sync runs immediately and typically finishes in a couple of minutes.
  


## What gets synced [#what-gets-synced]

| Object    | Fields                               | Refresh cadence |
| --------- | ------------------------------------ | --------------- |
| Workspace | workspace id, workspace name, bot id | Every 6 hours   |
| Members   | name, email, Notion user id, avatar  | Every 6 hours   |

The workspace appears as a SaaS app in your Layer inventory. Each human member with an email becomes a user node, joined to other identity sources by email. Bot users and members without an email are skipped.

## Permissions Layer never asks for [#permissions-layer-never-asks-for]

Layer does not request scopes for reading or modifying page content. The connector only calls Notion's `/users` endpoint and the workspace metadata returned during OAuth — page bodies and database rows are never fetched.

## Token refresh [#token-refresh]

Notion access tokens do not expire. If the Axiom integration is removed from your Notion workspace, the connection status changes to **needs re-auth** and you can reconnect with one click from **Integrations → Notion → Reconnect**.

## Member enumeration requires the right scope [#member-enumeration-requires-the-right-scope]

Listing workspace members uses Notion's `read_user_with_email` capability. If the OAuth grant doesn't include user-read access — for example, on workspaces where the integration was approved with a narrower scope — the workspace itself still syncs as a SaaS app, but no member nodes are created. Reconnect from **Integrations → Notion** and approve the user-read prompt to populate members.

## Troubleshooting [#troubleshooting]


  
    The OAuth grant didn't include the user-read capability, or every workspace member is a bot. Reconnect from **Integrations → Notion** and confirm the workspace approver granted access to read users.
  

  
    Notion signs you in as your most-recently-used workspace by default. On the consent screen, switch accounts or pick a different workspace from the picker before approving.
  

  
    Go to **Integrations → Notion → Disconnect** in Layer, then remove the Axiom integration from **Settings & members → Connections** in Notion.
  



# Okta (/layer/integrations/okta)



The Okta integration syncs users, groups, and per-app assignments — the foundation of license-true-up workflows in Layer.

## What you'll need [#what-youll-need]

* Okta **Super Admin** or a Read-Only Admin role.
* The ability to create an API token in your Okta tenant.
* Three minutes.

## Set it up [#set-it-up]


  
    ### Create an API token in Okta [#create-an-api-token-in-okta]

    In Okta Admin, go to **Security → API → Tokens** and click **Create Token**.

    Name it `Axiom Layer`. Copy the token value — you won't be able to see it again.
  

  
    ### Find your Okta domain [#find-your-okta-domain]

    Your Okta domain looks like `acme.okta.com` or `acme.oktapreview.com`. You can copy it from the URL bar of the Okta Admin console.
  

  
    ### Paste both into Layer [#paste-both-into-layer]

    In Layer, go to **Integrations**, find Okta, and click **Connect**. Paste your Okta domain and API token, then click **Connect**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately. Most tenants finish in under 15 minutes.
  


## What gets synced [#what-gets-synced]

| Object          | Fields                                   | Refresh cadence |
| --------------- | ---------------------------------------- | --------------- |
| Users           | login, email, status, last login         | Every 6 hours   |
| Groups          | name, description, member logins         | Every 6 hours   |
| Apps            | app name, provider, total assigned users | Every 6 hours   |
| App assignments | user → app links, assignment date        | Every 6 hours   |

### Per-user app access [#per-user-app-access]

Layer fetches each Okta user's assigned applications from `/api/v1/users/{userId}/appLinks` and creates:

* One **App** asset per distinct Okta-managed application (visible in the Apps view).
* One **Uses** relationship per user → app pairing, with the original Okta assignment date stored as `assigned_at` metadata.

This is what powers license true-up, SaaS spend reconciliation, and offboarding checks against your Okta-managed apps. Pagination is followed automatically, so tenants with hundreds of users or apps sync completely.

## Required token permissions [#required-token-permissions]

The token inherits the role of the admin who created it. **Read-Only Admin** is sufficient — Layer never writes to your Okta tenant.

## Troubleshooting [#troubleshooting]


  
    The token may have been revoked or copied incorrectly. Generate a new one and re-enter it in Layer.
  

  
    Apps that have no assigned users or groups won't appear. Apps in the Okta Integration Network catalog but not added to your tenant also won't appear — only apps actually configured in your Okta tenant are returned.
  



# OneLogin (/layer/integrations/onelogin)



The OneLogin integration syncs users, every app in your OneLogin catalog, and per-user app assignments — so OneLogin-fronted SaaS shows up in Layer's asset inventory with the actual user roster attached.

## What you'll need [#what-youll-need]

* A OneLogin **Account Owner** or **Super User** role.
* The ability to create an API credential pair (`client_id` + `client_secret`) in your OneLogin tenant.
* Three minutes.

## Set it up [#set-it-up]


  
    ### Create an API credential pair in OneLogin [#create-an-api-credential-pair-in-onelogin]

    In OneLogin Admin, go to **Developers → API Credentials** and click **New Credential**.

    Name it `Axiom Layer` and select the **Manage Users** scope. Click **Save**, then copy the `Client ID` and `Client Secret` — the secret is only shown once.
  

  
    ### Find your OneLogin subdomain [#find-your-onelogin-subdomain]

    Your OneLogin subdomain is the prefix on your Admin console URL — for example, `acme` for `acme.onelogin.com`. You can copy it from the URL bar of the OneLogin Admin console.
  

  
    ### Paste the credentials into Layer [#paste-the-credentials-into-layer]

    In Layer, go to **Integrations**, find OneLogin, and click **Connect**. Paste your subdomain, client ID, and client secret, then click **Connect**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync runs immediately. Most tenants finish in under 15 minutes.
  


## What gets synced [#what-gets-synced]

| Object          | Fields                              | Refresh cadence |
| --------------- | ----------------------------------- | --------------- |
| Users           | email, status, OneLogin user ID     | Every 6 hours   |
| Apps            | app name, auth method, connector ID | Every 6 hours   |
| App assignments | user → app links                    | Every 6 hours   |

### Per-user app access [#per-user-app-access]

Layer fetches each OneLogin app's assigned users from `/api/2/apps/{appId}/users` and creates:

* One **App** asset per app in your OneLogin catalog (visible in the Apps view), with the OneLogin app ID, auth method, and connector ID stored as metadata.
* One **Uses** relationship per user → app pairing.

This is what powers license true-up, SaaS spend reconciliation, and offboarding checks against your OneLogin-managed apps. Pagination is followed automatically, and per-app user enumeration is non-fatal — if the credential is missing the **Manage Users** scope, the SaaS app inventory still lands and Layer skips assignment emission silently.

## Required scopes [#required-scopes]

The API credential needs **Manage Users** to enumerate per-app user assignments. **Read Users** alone is enough for the user roster and the app catalog, but per-user app assignments will be empty without **Manage Users**. Layer never writes to your OneLogin tenant.

## Troubleshooting [#troubleshooting]


  
    The client ID or client secret may have been copied incorrectly, or the credential was revoked. Generate a new credential pair and re-enter both values in Layer.
  

  
    The credential is missing the **Manage Users** scope. Edit the credential in **Developers → API Credentials** and grant **Manage Users**, then run **Sync now** in Layer.
  

  
    Go to **Integrations → OneLogin → Disconnect** in Layer. To fully revoke, also delete the API credential under **Developers → API Credentials** in the OneLogin Admin console.
  



# Integrations overview (/layer/integrations/overview)





Layer connects to the systems your IT, security, and finance teams already use. The catalog only lists connectors with a working backend — every integration you see can sync real data today. Pick the one you want to set up and follow the guide.

## Identity and directory [#identity-and-directory]


  
    Sync users, groups, and app activity. One-click admin consent.
  

  
    Sync users, groups, devices, and audit logs. One-click admin consent.
  

  
    Sync users, groups, and app assignments via API token.
  

  
    Sync users, groups, memberships, and SSO-derived SaaS apps via API key.
  


## Communication and collaboration [#communication-and-collaboration]


  
    Discover Slack-Connect channels, app installs, and member counts.
  

  
    Inventory the workspace and its members via one-click OAuth.
  

  
    Sync users, groups, Jira projects, and Confluence spaces. One OAuth sign-in covers both products.
  


## Devices (MDM) [#devices-mdm]


  
    Sync managed devices, compliance policies, and conditional access rules. One-click admin consent or manual credentials.
  

  
    Inventory managed Mac, iPhone, and iPad devices via API client credentials.
  


## Security and compliance [#security-and-compliance]


  
    Inventory endpoint devices, open detections, and prevention policies.
  

  
    Collect monitor uptime, downtime schedules, and log retention evidence.
  


## Cloud infrastructure [#cloud-infrastructure]


  
    Inventory IAM users, S3 buckets, and generate access-control evidence.
  

  
    Inventory subscriptions, resource groups, and RBAC role assignments.
  

  
    Inventory IAM policy bindings and collect Cloud Audit Log summaries.
  


## Request a connector [#request-a-connector]

If you need a connector that isn't listed, you can request one directly from the Layer dashboard. Open the **Integrations** page and click **Request a connector** at the bottom of the catalog. The most-requested integrations are prioritized on the roadmap.

You can also email [hello@axiomlayer.io](mailto:hello@axiomlayer.io?subject=Connector%20request) with the tool name and a short description of your use case.

## Related [#related]

* **Compliance evidence**: every integration here feeds [Axiom Codex](/codex/getting-started) — see the [SOC 2 evidence catalog](/codex/soc2-evidence-catalog) for which controls each connector satisfies.
* **Token security**: read about how Layer encrypts and rotates IdP tokens in the [Microsoft 365](/layer/integrations/microsoft-365#token-refresh) guide.
* **Recent changes**: see the [changelog](/changelog) for the latest integrations shipped.


# Slack (/layer/integrations/slack)



The Slack integration discovers third-party apps installed in your workspace, Slack Connect channels with external companies, and per-channel member counts. New connections use a one-click OAuth flow brokered through Auth0 — there's no token to paste.

## What you'll need [#what-youll-need]

* Slack workspace **Owner** or **Admin** role.
* Two minutes.

## Set it up [#set-it-up]


  
    ### Open the Slack integration in Layer [#open-the-slack-integration-in-layer]

    In Layer, go to **Integrations**, find Slack, and click **Sign in with Slack**.
  

  
    ### Approve the OAuth scopes in Slack [#approve-the-oauth-scopes-in-slack]

    You'll be redirected to Slack's authorization screen. Pick the workspace you want to connect and review the requested bot scopes:

    * `users:read`, `users:read.email` — list workspace members
    * `channels:read`, `groups:read` — list public and private channels
    * `team:read` — read workspace metadata
    * `apps:read` — list installed third-party apps

    Click **Allow**.
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    You'll land back at **Integrations** with the Slack card marked connected. The initial sync runs immediately and typically finishes in under five minutes.
  


## What gets synced [#what-gets-synced]

| Object                 | Fields                                                | Refresh cadence |
| ---------------------- | ----------------------------------------------------- | --------------- |
| Members                | name, email, title, deactivated state                 | Every 6 hours   |
| Channels               | name, type (public / private / connect), member count | Every 6 hours   |
| Installed apps         | app name, installer, install date, scopes             | Daily           |
| Slack Connect channels | external workspace name, external member count        | Daily           |

## Permissions Layer never asks for [#permissions-layer-never-asks-for]

We do not request `channels:history`, `groups:history`, or any scope that would let us read message contents.

## Token refresh [#token-refresh]

Slack access tokens do not expire on their own, but they can be revoked by a workspace admin or if the Axiom app is uninstalled. If that happens, the connection status changes to **needs re-auth** and you can reconnect with one click from **Integrations → Slack → Reconnect**.

## Existing bot-token connections [#existing-bot-token-connections]

Tenants that connected before the OAuth flow shipped used a manually-pasted Slack bot token (`xoxb-...`). Those connections continue to work unchanged — Layer reads the legacy `bot_token` field first and falls back to the new OAuth `access_token` automatically. When you reconnect or rotate credentials, the new OAuth flow takes over and replaces the bot token.

## Troubleshooting [#troubleshooting]


  
    The authorizing user may not be a workspace admin. Reconnect with an Owner or Admin Slack account.
  

  
    Slack signs you in as your most-recently-used workspace by default. Click **Sign into a different workspace** on the consent screen and pick the tenant you want to connect.
  

  
    Go to **Integrations → Slack → Disconnect** in Layer, then revoke the Axiom app at [my.slack.com/apps/manage](https://my.slack.com/apps/manage).
  



# Workday (/layer/integrations/workday)



The Workday integration pulls your full worker roster from Workday's REST API v1 and feeds it into Layer's **People** view. Each worker becomes a `User` asset with department, title, manager, cost center, hire date, and termination date. Active, on-leave, and terminated workers all sync — Layer maps Workday's worker state to Layer's user status so [offboarding](/layer/offboarding) workflows fire the moment a termination is recorded in Workday.

## What you'll need [#what-youll-need]

* Workday **Integration System User (ISU)** or OAuth-enabled service account with read access to the Workers REST API.
* Your tenant's REST API base URL (e.g. `https://wd5-services1.workday.com/ccx/api/v1/{tenantAlias}`).
* A bearer token from Workday OAuth 2.0.
* Five minutes.

## Set it up [#set-it-up]


  
    ### Provision an integration system user in Workday [#provision-an-integration-system-user-in-workday]

    In Workday, create an **Integration System User** with read access to **Workers** and the **Public Reports** domain. Workday's documentation calls this the *REST API access* permission set. Assign the ISU a security group that scopes it to read-only.
  

  
    ### Generate an OAuth bearer token [#generate-an-oauth-bearer-token]

    Workday issues short-lived OAuth 2.0 tokens. Use the client-credentials grant against your tenant's token endpoint, scoped to the ISU above. The resulting `access_token` is what Layer uses on each sync.

    Layer does not orchestrate the token mint — paste the most recent token into the connect modal, and rotate it on your usual cadence.
  

  
    ### Find your REST API base URL [#find-your-rest-api-base-url]

    Your tenant's base URL is in the format `https://{cluster}.workday.com/ccx/api/v1/{tenantAlias}`. Workday admins can find it under **Setup → Integrations → REST API** in the Workday UI.
  

  
    ### Paste credentials into Layer [#paste-credentials-into-layer]

    In Layer, go to **Integrations**, find Workday, click **Connect**, and paste:

    * **API Base URL** — the full path including `/ccx/api/v1/{tenantAlias}`
    * **Access Token** — the bearer token from step 2
  

  
    ### Wait for the first sync [#wait-for-the-first-sync]

    The initial sync paginates through `/workers` 100 records at a time. A 5,000-employee tenant typically completes in under five minutes.
  


## What gets synced [#what-gets-synced]

| Field            | Source                                                 | Notes                                                               |
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| Employee name    | `descriptor`                                           | Full name as Workday renders it                                     |
| Email            | `primaryWorkEmail` / `workEmail`                       | Used as the canonical identity when present                         |
| Department       | `primarySupervisoryOrganization.descriptor`            | Used in cost roll-ups                                               |
| Title            | `primaryJob.businessTitle`                             |                                                                     |
| Location         | `primaryJob.location.descriptor`                       |                                                                     |
| Manager          | `primaryJob.manager` (falling back to `reportsTo`)     | Manager id, name, and email are captured from the manager reference |
| Management level | `primaryJob.managementLevel.descriptor`                |                                                                     |
| Cost center      | `primarySupervisoryOrganization.costCenter.descriptor` |                                                                     |
| Hire date        | `hireDate`                                             |                                                                     |
| Termination date | `terminationDate`                                      | Triggers [offboarding](/layer/offboarding) when set                 |

Workers without a primary work email are still synced and identified by their Workday worker ID (`workday:{workerId}`).

## Worker status mapping [#worker-status-mapping]

Layer maps Workday's worker state to its own user status:

| Workday state       | Layer status   |
| ------------------- | -------------- |
| Active              | **Active**     |
| On leave            | **Suspended**  |
| Terminated, retiree | **Offboarded** |

When a worker's status flips to **Offboarded**, Layer creates an offboarding task automatically if your org has any other Layer integrations (Microsoft 365, Google Workspace, Okta, etc.) connected — see [offboarding](/layer/offboarding) for the full action plan.

## Troubleshooting [#troubleshooting]


  
    Workday OAuth tokens are short-lived. Mint a fresh token using the client-credentials grant against your tenant's token endpoint and paste it into Layer. Layer does not refresh Workday tokens automatically — connect a token-refresh automation on your side, or rotate the token at the cadence Workday issues.
  

  
    Confirm the ISU has read access to the **Workers** domain at the tenant level, not just to a specific supervisory organization. Layer paginates `/workers` with no filter, so missing rows usually indicate scoped security.
  

  
    Workday exposes work email differently depending on the tenant's HR data model. Layer reads `primaryWorkEmail`, `workEmail.emailAddress`, and `primaryEmailAddress` in that order. If none are populated, the worker is still synced and identified by their Workday worker ID — pair Workday with [Microsoft 365](/layer/integrations/microsoft-365) or [Google Workspace](/layer/integrations/google-workspace) so the email surfaces from the IdP instead.
  



# Analytics (/locus/api/analytics)



## `GET` `/api/activity-heatmap` [#get-apiactivity-heatmap]

National activity feed aggregated to H3 resolution-5 hexagons. Returns a GeoJSON `FeatureCollection` of geocoded events from the last 90 days, weighted by event count per cell. Use this to power map-based heatmap visualizations of where activity is happening across the country, without scoping to a single metro.

The response is cached at the edge for 1 hour (`s-maxage=3600`, `stale-while-revalidate=86400`), so it's safe to fetch once on map mount instead of refetching as the viewport changes. There are no query parameters — the window and resolution are fixed.

Event counts per cell are long-tailed (p50 ≈ 22, p99 ≈ 270, max in the thousands). The `weight` field is the raw count; apply your own log or interpolation curve when styling heatmap layers so dense metros don't saturate the legend.

**Example**

```bash
curl "https://axiomlocus.io/api/activity-heatmap"
```

**Mapbox GL example**

```js
const res = await fetch("https://axiomlocus.io/api/activity-heatmap");
const fc = await res.json();

map.addSource("activity", { type: "geojson", data: fc });
map.addLayer({
  id: "activity-heatmap",
  type: "heatmap",
  source: "activity",
  paint: {
    "heatmap-weight": [
      "interpolate", ["linear"], ["get", "weight"],
      0, 0, 25, 0.2, 75, 0.45, 200, 0.75, 500, 1,
    ],
  },
});
```

**Response**

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-122.4194, 37.7749] },
      "properties": { "weight": 287, "h3": "852830fffffffff" }
    }
  ],
  "meta": {
    "window_days": 90,
    "parent_res": 5,
    "hex_count": 412
  }
}
```

| Field                             | Type         | Description                                                 |
| --------------------------------- | ------------ | ----------------------------------------------------------- |
| `features[].geometry.coordinates` | `[lng, lat]` | Center of the H3 res-5 hexagon.                             |
| `features[].properties.weight`    | int          | Number of events that occurred in this hex over the window. |
| `features[].properties.h3`        | string       | H3 res-5 cell index.                                        |
| `meta.window_days`                | int          | Lookback window in days (currently `90`).                   |
| `meta.parent_res`                 | int          | H3 resolution of the aggregation (currently `5`).           |
| `meta.hex_count`                  | int          | Number of hexes with at least one event.                    |

## `GET` `/api/heatmap/[dimension]` [#get-apiheatmapdimension]

Generic single-dimension density heatmap. Returns a GeoJSON `FeatureCollection` of H3 res-5 hexagons weighted by the raw magnitude of the requested dimension, aggregated across the entire dataset (no metro scope, no time window). Use this to underlay a single raw signal beneath the Explorer's scored [`/api/activity-heatmap`](#get-apiactivity-heatmap) or [Fit](/locus/explorer#heatmap-layers) layers — for example, painting crime density under a Safety-weighted Fit map to spot cells that scored well *despite* elevated raw crime.

The route is public and rate-limited (surfaces `X-RateLimit-Remaining`), and its response is edge-cached for 1 hour (`s-maxage=3600`, `stale-while-revalidate=86400`).

**Path parameters**

| Name        | Type   | Description                                                                                                |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `dimension` | string | Which dimension to aggregate. Currently supported: `crime`. Requesting an unknown dimension returns `400`. |


  Each dimension maps to a source table and an optional magnitude column. When the dimension has no magnitude column, the weight is the count of rows per parent hex. Additional dimensions (for example, an H3-keyed rent-growth series) can be added as their source tables land; the response shape is identical.


**Example**

```bash
curl "https://axiomlocus.io/api/heatmap/crime"
```

**Response**

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-122.4194, 37.7749] },
      "properties": { "h3": "852830fffffffff", "weight": 142 }
    }
  ],
  "meta": {
    "dimension": "crime",
    "parent_res": 5,
    "hex_count": 318
  }
}
```

| Field                             | Type         | Description                                                                                           |
| --------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `features[].geometry.coordinates` | `[lng, lat]` | Center of the H3 res-5 hexagon.                                                                       |
| `features[].properties.h3`        | string       | H3 res-5 cell index.                                                                                  |
| `features[].properties.weight`    | number       | Sum of the dimension's magnitude for this hex (row count when the dimension has no magnitude column). |
| `meta.dimension`                  | string       | Echoes the requested dimension.                                                                       |
| `meta.parent_res`                 | int          | H3 resolution of the aggregation (currently `5`).                                                     |
| `meta.hex_count`                  | int          | Number of hexes with a non-zero weight.                                                               |

**Errors**

| Status | When                                      |
| ------ | ----------------------------------------- |
| `400`  | The requested dimension is not supported. |
| `429`  | Rate limit exceeded.                      |
| `500`  | Backend query failed.                     |

## `GET` `/api/permits/hotspots` [#get-apipermitshotspots]

H3-aggregated building permit hotspots for a metro, ranked by permit density and total estimated cost.

**Query parameters**

| Name         | Type   | Required | Default | Description                         |
| ------------ | ------ | -------- | ------- | ----------------------------------- |
| `metro_slug` | string | ✓        |         | Metro slug (e.g. sf, nyc, chi, la). |
| `days`       | int    |          | `90`    | Lookback period in days.            |
| `limit`      | int    |          | `25`    | Max hotspot cells to return.        |

**Example**

```bash
curl "https://axiomlocus.io/api/permits/hotspots?metro_slug=sf&days=90&limit=10"
```

**Response**

```json
{
  "metro": "sf",
  "days": 90,
  "hotspots": [
    {
      "h3_index": "882a100d63fffff",
      "center_lat": 37.7749,
      "center_lng": -122.4194,
      "permit_count": 47,
      "total_value": 12500000,
      "avg_value": 265957,
      "top_type": "new_construction"
    },
    {
      "h3_index": "882a100d65fffff",
      "center_lat": 37.7851,
      "center_lng": -122.4094,
      "permit_count": 32,
      "total_value": 8700000,
      "avg_value": 271875,
      "top_type": "renovation"
    }
  ]
}
```

| Field                     | Type   | Description                           |
| ------------------------- | ------ | ------------------------------------- |
| `hotspots`                | array  | H3 cells ranked by permit activity.   |
| `hotspots[].permit_count` | int    | Total permits in the lookback window. |
| `hotspots[].total_value`  | float  | Sum of estimated costs.               |
| `hotspots[].top_type`     | string | Most common permit type in this cell. |

## `GET` `/api/crime/hotspots` [#get-apicrimehotspots]

Crime incident hotspots aggregated by H3 cell for a metro area.

**Query parameters**

| Name         | Type   | Required | Default | Description                                         |
| ------------ | ------ | -------- | ------- | --------------------------------------------------- |
| `metro_slug` | string | ✓        |         | Metro slug.                                         |
| `days`       | int    |          | `90`    | Lookback period in days.                            |
| `category`   | string |          |         | Filter by crime category: property, violent, other. |
| `limit`      | int    |          | `25`    | Max cells to return.                                |

**Example**

```bash
curl "https://axiomlocus.io/api/crime/hotspots?metro_slug=sf&days=30&category=property"
```

**Response**

```json
{
  "metro": "sf",
  "days": 30,
  "total_incidents": 1243,
  "hotspots": [
    {
      "h3_index": "882a100d63fffff",
      "incident_count": 89,
      "top_category": "property",
      "per_capita_rate": 12.4,
      "trend": "declining"
    }
  ]
}
```

| Field                        | Type   | Description                                              |
| ---------------------------- | ------ | -------------------------------------------------------- |
| `total_incidents`            | int    | Total incidents across all cells in the lookback window. |
| `hotspots[].incident_count`  | int    | Number of incidents in this H3 cell.                     |
| `hotspots[].per_capita_rate` | float  | Incidents per 1,000 residents.                           |
| `hotspots[].trend`           | string | Trend vs prior period: increasing, stable, declining.    |

## `GET` `/api/commuter-flows` [#get-apicommuter-flows]

LEHD Origin-Destination commuter flow data for a Census tract. Shows where workers live and where residents work.

**Query parameters**

| Name        | Type   | Required | Default | Description                                                         |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `tract`     | string | ✓        |         | Census tract GEOID (11 digits).                                     |
| `direction` | string |          | `both`  | inbound (workers coming in), outbound (residents leaving), or both. |
| `limit`     | int    |          | `20`    | Top N connected tracts to return.                                   |

**Example**

```bash
curl "https://axiomlocus.io/api/commuter-flows?tract=06075010800&direction=inbound&limit=10"
```

**Response**

```json
{
  "tract": "06075010800",
  "inbound": {
    "total_workers": 14200,
    "flows": [
      { "origin_tract": "06081611100", "workers": 890, "pct": 6.3, "origin_name": "Daly City" },
      { "origin_tract": "06001402100", "workers": 720, "pct": 5.1, "origin_name": "Oakland" }
    ]
  },
  "outbound": {
    "total_residents_working": 3400,
    "flows": [
      { "dest_tract": "06075017902", "workers": 210, "pct": 6.2, "dest_name": "SoMa" }
    ]
  }
}
```

| Field                              | Type  | Description                              |
| ---------------------------------- | ----- | ---------------------------------------- |
| `inbound.total_workers`            | int   | Total workers commuting into this tract. |
| `inbound.flows`                    | array | Top origin tracts with worker counts.    |
| `outbound.total_residents_working` | int   | Total residents who commute out.         |
| `outbound.flows`                   | array | Top destination tracts.                  |

## `GET` `/api/v1/spatial-diagnostics` [#get-apiv1spatial-diagnostics]


  Requires Bearer token.


Identify spatial score outliers using Local Moran's I (LISA) statistics and topological data analysis. Use this to find cells that behave differently from their neighbors — high-scoring cells surrounded by low scores, or vice versa.

**Query parameters**

| Name         | Type   | Required | Default | Description                                                                                                                        |
| ------------ | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `metro_slug` | string |          |         | Filter by metro area.                                                                                                              |
| `type`       | string |          |         | Spatial cluster type: `HH` (High-High), `HL` (High-Low), `LH` (Low-High), `LL` (Low-Low), `TDA_DONUT` (topological donut pattern). |
| `limit`      | int    |          | `50`    | Max results (max 500).                                                                                                             |

**Cluster types explained:**

| Type        | Meaning                               | Use case                                                                            |
| ----------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `HH`        | High score surrounded by high scores  | Established strong markets.                                                         |
| `HL`        | High score surrounded by low scores   | Potential anchor locations driving change.                                          |
| `LH`        | Low score surrounded by high scores   | Underperforming cells in strong markets — possible opportunities.                   |
| `LL`        | Low score surrounded by low scores    | Weak market clusters.                                                               |
| `TDA_DONUT` | Ring of activity with a hollow center | Emerging development patterns where activity surrounds but hasn't reached the core. |

When no `type` is specified, the endpoint returns `HL` and `LH` outliers — the most analytically interesting patterns.

**Example**

```bash
curl "https://axiomlocus.io/api/v1/spatial-diagnostics?metro_slug=sf&type=HL&limit=10" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{
  "outliers": [
    {
      "h3_index": "882a100d63fffff",
      "metro_slug": "sf",
      "score_baseline": 72,
      "experimental_composite": 78,
      "spatial_diagnostics": {
        "cluster_type": "HL",
        "local_moran": 2.34
      }
    }
  ]
}
```

| Field                                         | Type   | Description                                                                                   |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `outliers`                                    | array  | Cells matching the spatial pattern, sorted by statistical significance.                       |
| `outliers[].score_baseline`                   | number | Current composite score.                                                                      |
| `outliers[].spatial_diagnostics.cluster_type` | string | LISA cluster classification.                                                                  |
| `outliers[].spatial_diagnostics.local_moran`  | number | Local Moran's I statistic. Higher absolute values indicate stronger spatial outlier behavior. |

## `GET` `/api/backtest` [#get-apibacktest]


  Requires authentication. Session-based — available through the dashboard.


Validate scoring model accuracy by comparing historical predictions against outcomes. Requires at least 90 days of score history and 5 or more monitored locations.

**Example**

```bash
curl "https://axiomlocus.io/api/backtest" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response (ready)**

```json
{
  "status": "ready",
  "data_collection_start": "2026-01-15",
  "days_of_data": 94,
  "metrics": {
    "r_squared": 0.82,
    "hit_rate": 0.76,
    "miss_rate": 0.68,
    "sample_size": 12
  }
}
```

**Response (insufficient data)**

```json
{
  "status": "insufficient_data",
  "days_until_ready": 42,
  "days_of_data": 48,
  "data_collection_start": "2026-03-01",
  "sample_size": 3
}
```

| Field                 | Type   | Description                                                               |
| --------------------- | ------ | ------------------------------------------------------------------------- |
| `status`              | string | `ready` or `insufficient_data`.                                           |
| `metrics.r_squared`   | number | Correlation between predicted and actual scores (0–1).                    |
| `metrics.hit_rate`    | number | Fraction of high-scored locations (above 70) that maintained or improved. |
| `metrics.miss_rate`   | number | Fraction of low-scored locations (below 30) that stayed low or declined.  |
| `metrics.sample_size` | number | Number of location pairs used in the analysis.                            |


# Core Scoring (/locus/api/core-scoring)



## `GET` `/api/score` [#get-apiscore]

Score a location across all 8 signal groups.

**Query parameters**

| Name      | Type   | Required | Default   | Description                                                                                                            |
| --------- | ------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `lat`     | float  | ✓        |           | Latitude of the location.                                                                                              |
| `lng`     | float  | ✓        |           | Longitude of the location.                                                                                             |
| `radius`  | float  |          | `1.0`     | Radius in km (max 10).                                                                                                 |
| `profile` | string |          | `general` | Scoring profile. One of: `general`, `qsr`, `self_storage`, `retail`, `office`, `data_center`, `industrial`.            |
| `include` | string |          |           | Comma-separated extras: `uncertainty`, `esgi`. Adds uncertainty quantification or Pioneer Signal data to the response. |

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://axiomlocus.io/api/score",
        params={"lat": 37.7749, "lng": -122.4194, "profile": "general"},
    )
    score = res.json()  # {"composite": 78.4, "confidence": 0.92, "groups": {...}}
    ```
  

  
    ```js
    const url = new URL("https://axiomlocus.io/api/score");
    url.searchParams.set("lat", "37.7749");
    url.searchParams.set("lng", "-122.4194");

    const score = await fetch(url).then((r) => r.json());
    ```
  


**Response**

```json
{
  "composite": 78.4,
  "confidence": 0.92,
  "sourcesUsed": 36,
  "sourcesTotal": 43,
  "metro": "sf",
  "profile": "general",
  "groups": {
    "businessVitality": {
      "score": 82.1,
      "confidence": 1.0,
      "sourcesActive": 5,
      "sourcesTotal": 6,
      "subScores": [
        { "name": "Net Business Openings", "score": 71 },
        { "name": "Category Diversity", "score": 88 },
        { "name": "Rating Trajectory", "score": 79 }
      ]
    }
  }
}
```

| Field          | Type   | Description                                                                                    |
| -------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `composite`    | float  | Overall score from 0 to 100.                                                                   |
| `confidence`   | float  | Data completeness ratio from 0.0 to 1.0.                                                       |
| `sourcesUsed`  | int    | Number of data sources that returned data.                                                     |
| `sourcesTotal` | int    | Total possible data sources.                                                                   |
| `metro`        | string | Metro slug where the location was resolved.                                                    |
| `profile`      | string | Scoring profile used.                                                                          |
| `groups`       | object | Per-signal-group breakdown with score, confidence, sourcesActive, sourcesTotal, and subScores. |

## `POST` `/api/bulk-score` [#post-apibulk-score]


  Requires Bearer token.


Score up to 50 locations in a single request.

**Request body**

```json
{
  "locations": [
    { "lat": 37.7749, "lng": -122.4194 },
    { "lat": 34.0522, "lng": -118.2437 }
  ],
  "radius": 1.0,
  "profile": "qsr"
}
```

| Field       | Type   | Required | Default   | Description                                                                                                                   |
| ----------- | ------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `locations` | array  | ✓        |           | Array of \{ lat, lng } objects. Maximum 50.                                                                                   |
| `radius`    | float  |          | `1.0`     | Radius in km (max 10). Applied to all locations.                                                                              |
| `profile`   | string |          | `general` | Scoring profile for all locations. One of: `general`, `qsr`, `self_storage`, `retail`, `office`, `data_center`, `industrial`. |

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl -X POST "https://axiomlocus.io/api/bulk-score" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_TOKEN" \
      -d '{"locations":[{"lat":37.77,"lng":-122.41},{"lat":34.05,"lng":-118.24}]}'
    ```
  

  
    ```python
    import requests

    res = requests.post(
        "https://axiomlocus.io/api/bulk-score",
        headers={"Authorization": "Bearer YOUR_TOKEN"},
        json={
            "locations": [
                {"lat": 37.77, "lng": -122.41},
                {"lat": 34.05, "lng": -118.24},
            ],
            "profile": "qsr",
        },
    )
    results = res.json()["results"]
    ```
  

  
    ```js
    const res = await fetch("https://axiomlocus.io/api/bulk-score", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer YOUR_TOKEN",
      },
      body: JSON.stringify({
        locations: [
          { lat: 37.77, lng: -122.41 },
          { lat: 34.05, lng: -118.24 },
        ],
        profile: "qsr",
      }),
    });
    const { results } = await res.json();
    ```
  


**Response**

```json
{
  "results": [
    {
      "lat": 37.77,
      "lng": -122.41,
      "composite": 78.4,
      "confidence": 0.92,
      "groups": { "..." : "..." }
    },
    {
      "lat": 34.05,
      "lng": -118.24,
      "composite": 71.2,
      "confidence": 0.88,
      "groups": { "..." : "..." }
    }
  ]
}
```

| Field                  | Type   | Description                                     |
| ---------------------- | ------ | ----------------------------------------------- |
| `results`              | array  | Array of score objects, one per input location. |
| `results[].composite`  | float  | Composite score (0-100) for the location.       |
| `results[].confidence` | float  | Data completeness ratio.                        |
| `results[].groups`     | object | Signal group breakdown.                         |


# Data (/locus/api/data)



## `GET` `/api/ports` [#get-apiports]

Container and cargo volume data for US ports. Includes TEU throughput, year-over-year trends, and vessel calls.

**Query parameters**

| Name        | Type   | Required | Default | Description                                                 |
| ----------- | ------ | -------- | ------- | ----------------------------------------------------------- |
| `port_slug` | string | ✓        |         | Port slug (e.g. la-lb, savannah, houston, newark, oakland). |
| `months`    | int    |          | `12`    | Months of historical data.                                  |

**Example**

```bash
curl "https://axiomlocus.io/api/ports?port_slug=la-lb&months=6"
```

**Response**

```json
{
  "port_slug": "la-lb",
  "port_name": "Port of Los Angeles / Long Beach",
  "latest_teu": 892000,
  "yoy_change_pct": 8.4,
  "monthly": [
    { "month": "2026-03", "teu": 892000, "vessel_calls": 142 },
    { "month": "2026-02", "teu": 845000, "vessel_calls": 138 },
    { "month": "2026-01", "teu": 801000, "vessel_calls": 131 }
  ]
}
```

| Field                    | Type  | Description                                                   |
| ------------------------ | ----- | ------------------------------------------------------------- |
| `latest_teu`             | int   | Most recent month's TEU (twenty-foot equivalent unit) volume. |
| `yoy_change_pct`         | float | Year-over-year percentage change.                             |
| `monthly`                | array | Monthly volume breakdown.                                     |
| `monthly[].vessel_calls` | int   | Number of vessel arrivals that month.                         |

## `GET` `/api/construction` [#get-apiconstruction]

Satellite-detected construction activity in a metro. Uses change detection on Sentinel-2 imagery to identify active sites.

**Query parameters**

| Name            | Type   | Required | Default | Description                          |
| --------------- | ------ | -------- | ------- | ------------------------------------ |
| `metro_slug`    | string | ✓        |         | Metro slug.                          |
| `days`          | int    |          | `30`    | Lookback window in days.             |
| `min_area_sqft` | int    |          | `5000`  | Minimum detected site area in sq ft. |

**Example**

```bash
curl "https://axiomlocus.io/api/construction?metro_slug=austin&days=60"
```

**Response**

```json
{
  "metro": "austin",
  "days": 60,
  "total_detections": 34,
  "detections": [
    {
      "h3_index": "882a107a0bfffff",
      "center_lat": 30.2672,
      "center_lng": -97.7431,
      "estimated_area_sqft": 45000,
      "confidence": 0.91,
      "first_detected": "2026-02-15",
      "last_detected": "2026-03-28",
      "nearest_permit_id": "P-2025-9876"
    }
  ]
}
```

| Field                              | Type   | Description                                   |
| ---------------------------------- | ------ | --------------------------------------------- |
| `total_detections`                 | int    | Number of detected active construction sites. |
| `detections[].estimated_area_sqft` | int    | Estimated site footprint in square feet.      |
| `detections[].confidence`          | float  | Detection confidence score (0-1).             |
| `detections[].nearest_permit_id`   | string | Cross-referenced building permit if matched.  |


# Discovery & Intelligence (/locus/api/discovery-and-intelligence)



## `GET` `/api/discover` [#get-apidiscover]

Filter locations by score thresholds across all metros.

**Query parameters**

| Name           | Type   | Required | Default | Description                |
| -------------- | ------ | -------- | ------- | -------------------------- |
| `metro`        | string |          |         | Metro slug filter.         |
| `compositeMin` | int    |          |         | Minimum composite score.   |
| `businessMin`  | int    |          |         | Minimum Business Vitality. |
| `safetyMin`    | int    |          |         | Minimum Safety score.      |
| `limit`        | int    |          | `50`    | Max results.               |

**Example**

```bash
curl "https://axiomlocus.io/api/discover?metro=sf&compositeMin=60&safetyMin=50"
```

**Response**

```json
{ "total": 12, "results": [{ "h3_index": "...", "metro_slug": "sf", "location_name": "Mission District", "composite": 74 }] }
```

| Field                     | Type   | Description                  |
| ------------------------- | ------ | ---------------------------- |
| `total`                   | number | Number of matching locations |
| `results[].composite`     | number | Composite score 0-100        |
| `results[].location_name` | string | Neighborhood name            |

## `GET` `/api/saved-searches` [#get-apisaved-searches]


  Requires authentication.


List the caller's saved `/discover` filter sets, ordered from newest to oldest.

**Response**

```json
{
  "searches": [
    {
      "id": "8f1c2c4e-1c87-4a1b-9f8a-1f3d6c2c0e2b",
      "name": "Sunbelt high-vitality",
      "filters": { "metros": ["phx", "atl", "tpa"], "compositeMin": 65 },
      "created_at": "2026-04-29T10:14:02Z",
      "updated_at": "2026-04-29T10:14:02Z"
    }
  ]
}
```

| Field                   | Type   | Description                                       |
| ----------------------- | ------ | ------------------------------------------------- |
| `searches[].id`         | uuid   | Saved-search identifier                           |
| `searches[].name`       | string | User-supplied saved-search name                   |
| `searches[].filters`    | object | Opaque filter object stored with the saved search |
| `searches[].created_at` | string | Creation timestamp                                |
| `searches[].updated_at` | string | Most recent update timestamp                      |

Returns `401` for an unauthenticated caller and `500` when the list cannot be loaded.

## `POST` `/api/saved-searches` [#post-apisaved-searches]


  Requires authentication.


Create a named saved `/discover` filter set.

**Request body**

| Name      | Type   | Required | Description                                                                       |
| --------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `name`    | string | ✓        | Name after trimming; it must contain 1–120 characters                             |
| `filters` | object |          | Opaque filter object. Defaults to `{}` and its serialized JSON is capped at 8 KiB |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/saved-searches" \
  -H "content-type: application/json" \
  -d '{
    "name": "Sunbelt high-vitality",
    "filters": { "metros": ["phx", "atl", "tpa"], "compositeMin": 65 }
  }'
```

**Response** (`201 Created`)

```json
{
  "search": {
    "id": "8f1c2c4e-1c87-4a1b-9f8a-1f3d6c2c0e2b",
    "name": "Sunbelt high-vitality",
    "filters": { "metros": ["phx", "atl", "tpa"], "compositeMin": 65 },
    "created_at": "2026-04-29T10:14:02Z",
    "updated_at": "2026-04-29T10:14:02Z"
  }
}
```

| Status | When                                                                                                                                       |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | The JSON body is invalid, `name` is empty or longer than 120 characters, `filters` is not an object, or serialized `filters` exceeds 8 KiB |
| `401`  | The caller is unauthenticated                                                                                                              |
| `409`  | A saved search with that name already exists                                                                                               |
| `500`  | The saved search cannot be created                                                                                                         |

## `DELETE` `/api/saved-searches` [#delete-apisaved-searches]


  Requires authentication.


Delete a saved search that belongs to the caller.

**Query parameters**

| Name | Type | Required | Description             |
| ---- | ---- | -------- | ----------------------- |
| `id` | uuid | ✓        | Saved-search identifier |

**Example**

```bash
curl -X DELETE "https://axiomlocus.io/api/saved-searches?id=8f1c2c4e-1c87-4a1b-9f8a-1f3d6c2c0e2b"
```

**Response**

```json
{ "success": true }
```

Returns `400` when the `id` parameter is absent or not a valid UUID, `401` for an unauthenticated caller, `404` when no saved search with that id exists for the caller (including ids that belong to another user), and `500` when the delete cannot be completed.

## `POST` `/api/cells/similar` [#post-apicellssimilar]

Find the nearest look-alike cells to a given H3 cell by driver-profile or satellite-image signature. Unlike the same-metro "Comparable cells" section of the [Explorer](/locus/explorer#look-alike-cells) — which ranks by absolute composite-score distance within one metro — this endpoint ranks by *shape* similarity (cosine nearest-neighbor over a per-cell vector) and can look across every scored metro. Use it when you want to answer "where else does a place like this exist?"

Two similarity bases are supported today, plus a blend of the two:

| Mode              | Vector                                                                         | Meaning                                                                                                                                                 | Availability                                                                                                |
| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `score` (default) | 8-d cell score profile (the eight [signal groups](/locus/scoring-conventions)) | Two cells are similar when their signal *mix* looks alike — for example, "high business vitality, weak safety" — regardless of overall composite level. | Live for every scored cell.                                                                                 |
| `satellite`       | 64-d AlphaEarth satellite embedding                                            | Two cells are similar when their satellite-image signature looks alike — built form, greenness, land cover. Independent of the score.                   | Dormant until Earth Engine backfill lands. Returns `no_satellite_embedding` for cells without an embedding. |
| `blend`           | Average of the score and satellite distances                                   | Balances the two views.                                                                                                                                 | Same availability as `satellite` — both sides must be populated for the source and each candidate.          |

**Request body**

| Name            | Type   | Required | Default | Description                                                                                                           |
| --------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `h3Index`       | string | ✓        |         | The source H3 cell to look up neighbors for.                                                                          |
| `mode`          | string |          | `score` | Similarity basis: `score`, `satellite`, or `blend`.                                                                   |
| `limit`         | int    |          | `12`    | Max neighbors to return. Clamped to `[1, 100]`.                                                                       |
| `sameMetroOnly` | bool   |          | `false` | Restrict candidates to the source cell's metro. Off by default — the point of this endpoint is cross-metro discovery. |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/cells/similar" \
  -H "content-type: application/json" \
  -d '{ "h3Index": "882a100d63fffff", "mode": "score", "limit": 5 }'
```

**Response (found)**

```json
{
  "found": true,
  "sourceH3": "882a100d63fffff",
  "sourceMetro": "sf",
  "cells": [
    {
      "h3_index": "882a306833fffff",
      "metro_slug": "nyc",
      "lat": 40.7128,
      "lng": -74.0060,
      "composite": 71.2,
      "confidence": 0.86,
      "similarity": 0.972,
      "business_vitality": 78,
      "population_momentum": 65,
      "demographics": 70,
      "economic_strength": 74,
      "development_pipeline": 62,
      "accessibility": 88,
      "safety_environment": 55,
      "amenity_demand": 81
    }
  ]
}
```

**Response (source has no satellite embedding, satellite/blend mode)**

```json
{
  "found": false,
  "reason": "no_satellite_embedding",
  "sourceH3": "882a100d63fffff",
  "sourceMetro": "sf",
  "cells": []
}
```

| Field                                                                         | Type   | Description                                                                                                                                           |
| ----------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `found`                                                                       | bool   | `false` when the source cell is unknown, has an all-zero score profile, or (satellite/blend) has no embedding.                                        |
| `reason`                                                                      | string | Populated when `found=false` to explain why. `no_satellite_embedding` is the common case today — the cell is scored, but has no satellite vector yet. |
| `sourceH3`                                                                    | string | Echo of the requested H3 index.                                                                                                                       |
| `sourceMetro`                                                                 | string | Metro slug of the source cell, or `null` if the cell is unscored.                                                                                     |
| `cells[].similarity`                                                          | number | Cosine similarity to the source cell, in `[0, 1]`. `1.0` means an identical profile; `0.97` and above is a very tight match.                          |
| `cells[].composite`, `cells[].confidence`, and the eight signal-group columns | number | The neighbor's current score row, so you can render a preview without a follow-up call.                                                               |


  **Availability.** `score` mode is live: `feature_vec` is refreshed automatically as cells re-score. `satellite` and `blend` are gated on the AlphaEarth Earth Engine backfill — until embeddings exist, requests in those modes will return `found: false` with `reason: "no_satellite_embedding"`. Score mode is the correct default for production use today.



  Set `sameMetroOnly: true` if you want a within-metro comparison — for example, "find other cells in San Francisco that look like this one." Leaving it `false` (the default) is what makes this different from the Explorer's legacy same-metro comparables card.


## `GET` `/api/nearby` [#get-apinearby]

Everything we know near a location — permits, POIs, schools, clinical trials, FDA events, zoning.

**Query parameters**

| Name  | Type  | Required | Default | Description |
| ----- | ----- | -------- | ------- | ----------- |
| `lat` | float | ✓        |         | Latitude.   |
| `lng` | float | ✓        |         | Longitude.  |

**Example**

```bash
curl "https://axiomlocus.io/api/nearby?lat=37.7749&lng=-122.4194"
```

**Response**

```json
{ "summary": { "permits": 45, "pois": 120, "schools": 3, "clinical_trials": 8 }, "recent": { ... } }
```

| Field     | Type   | Description                                 |
| --------- | ------ | ------------------------------------------- |
| `summary` | object | Count of records per data type within \~1km |
| `recent`  | object | Recent records from each data type          |

## `GET` `/api/metro-tier-distribution` [#get-apimetro-tier-distribution]

Count of scored cells in each safety tier bucket for a given signal across a metro. Powers the tier-mix bar on the [Explorer Intelligence Rail](/locus/explorer#metro-key-stats) so you can see at a glance whether a metro is mostly safe or mostly elevated, without leaving the page.

Buckets follow the standard composite score breakpoints: **Prime ≥80**, **Strong 60–79**, **Solid 40–59**, **Watch 20–39**, **Elevated (below 20)**. Cells with a `null` value for the requested signal are excluded.

**Query parameters**

| Name     | Type   | Required | Default              | Description                                                                                                                                                                                                |
| -------- | ------ | -------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metro`  | string | ✓        |                      | Metro slug (e.g. `sf`, `nyc`, `denver`).                                                                                                                                                                   |
| `signal` | string |          | `safety_environment` | Column to bucket on. One of `composite`, `business_vitality`, `population_momentum`, `demographics`, `economic_strength`, `development_pipeline`, `accessibility`, `safety_environment`, `amenity_demand`. |

**Example**

```bash
curl "https://axiomlocus.io/api/metro-tier-distribution?metro=sf&signal=safety_environment"
```

**Response**

```json
{
  "metro": "sf",
  "signal": "safety_environment",
  "total": 1284,
  "buckets": {
    "prime": 412,
    "strong": 537,
    "solid": 246,
    "watch": 71,
    "elevated": 18
  }
}
```

| Field              | Type   | Description                                                                                               |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------- |
| `metro`            | string | Metro slug echoed from the request.                                                                       |
| `signal`           | string | Signal column the distribution is computed over.                                                          |
| `total`            | number | Total scored cells included in the distribution (cells with `null` on the requested signal are excluded). |
| `buckets.prime`    | number | Cells scoring ≥ 80.                                                                                       |
| `buckets.strong`   | number | Cells scoring 60–79.                                                                                      |
| `buckets.solid`    | number | Cells scoring 40–59.                                                                                      |
| `buckets.watch`    | number | Cells scoring 20–39.                                                                                      |
| `buckets.elevated` | number | Cells scoring \< 20.                                                                                      |

The same endpoint backs distribution bars for any signal group — pass a different `signal` to render a development-pipeline mix, business-vitality mix, or composite mix without a separate route.

## `GET` `/api/score-trends` [#get-apiscore-trends]

Historical score trends for a metro or specific H3 cell. Pass `metro` for a metro-wide aggregate trend or `h3_index` for a per-cell time-series with all eight signal-group sub-scores. Exactly one of the two is required.

The endpoint reads from the `score_history` table that the Railway scorer snapshots once per day, so a fresh row appears for every `(h3_index, profile, snapshot_date)` covered by that day's scorer pass. Cells the scorer didn't touch on a given day will be absent from the time-series for that date.

**Query parameters**

| Name       | Type   | Required | Default | Description                                                                  |
| ---------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- |
| `metro`    | string |          |         | Metro slug for an aggregate metro-wide trend.                                |
| `h3_index` | string |          |         | Specific H3 cell for a detailed per-cell trend with signal-group breakdowns. |
| `days`     | int    |          | `90`    | Lookback period in days.                                                     |

**Metro aggregate example**

```bash
curl "https://axiomlocus.io/api/score-trends?metro=sf&days=30"
```

```json
{ "metro": "sf", "days": 30, "trend": [{ "date": "2026-03-30", "avg_composite": 42, "cells": 20 }] }
```

| Field                   | Type   | Description                                            |
| ----------------------- | ------ | ------------------------------------------------------ |
| `trend[].date`          | string | Snapshot date (`YYYY-MM-DD`)                           |
| `trend[].avg_composite` | number | Average composite score across the metro for that date |
| `trend[].cells`         | number | Cells in the metro with a snapshot on that date        |

**Per-cell example**

```bash
curl "https://axiomlocus.io/api/score-trends?h3_index=882a1072d3fffff&days=90"
```

```json
{
  "h3_index": "882a1072d3fffff",
  "days": 90,
  "snapshots": [
    {
      "snapshot_date": "2026-04-29",
      "composite": 71,
      "business_vitality": 68,
      "population_momentum": 74,
      "demographics": 65,
      "economic_strength": 80,
      "development_pipeline": 77,
      "accessibility": 62,
      "safety_environment": 70,
      "amenity_demand": 64
    }
  ]
}
```

| Field                                                            | Type           | Description                                                                            |
| ---------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------- |
| `snapshots[].snapshot_date`                                      | string         | Snapshot date (`YYYY-MM-DD`)                                                           |
| `snapshots[].composite`                                          | number         | Cell composite score 0–100 on that date                                                |
| `snapshots[].business_vitality` ... `snapshots[].amenity_demand` | number \| null | Per-group sub-score 0–100; `null` if the group could not be computed for that snapshot |

## `GET` `/api/metro-permit-trend` [#get-apimetro-permit-trend]

Monthly building-permit counts for a metro over the requested lookback window.

**Query parameters**

| Name     | Type   | Required | Default | Description                                                                            |
| -------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------- |
| `metro`  | string | ✓        |         | Metro slug                                                                             |
| `months` | number |          | `12`    | Lookback window. Values from 1 through 36 are accepted; other values fall back to `12` |

**Example**

```bash
curl "https://axiomlocus.io/api/metro-permit-trend?metro=boston&months=3"
```

**Response**

```json
{
  "metro": "boston",
  "months": 3,
  "points": [
    { "month": "2026-05", "count": 98 },
    { "month": "2026-06", "count": 0 },
    { "month": "2026-07", "count": 121 }
  ],
  "total": 219,
  "available": true
}
```

| Field            | Type    | Description                                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------------- |
| `metro`          | string  | Metro slug echoed from the request                                                    |
| `months`         | number  | Lookback window used for the response                                                 |
| `points`         | array   | Dense monthly series for the requested window. Months without permits have `count: 0` |
| `points[].month` | string  | Month in `YYYY-MM` form                                                               |
| `points[].count` | number  | Permits issued in that month                                                          |
| `total`          | number  | Sum of the returned monthly counts                                                    |
| `available`      | boolean | `true` when `total` is greater than zero                                              |

The `metro` parameter is required; omitting it returns `400`. An unknown metro returns `{ metro, months, points: [], total: 0, available: false }` with a successful response. A permit-data query failure returns `500`.

## `GET` `/api/top-movers` [#get-apitop-movers]

Discover the cells whose composite score has changed the most over a 7-, 30-, 90-, or 180-day window. Each row reports the latest composite, the prior-window composite, and the delta between them, so you can surface neighborhoods that are heating up (or cooling off) without manually diffing snapshots from [`/api/score-trends`](#get-apiscore-trends).

Deltas are computed against the freshest snapshot in `score_history` at or before the lookback boundary, not a fixed calendar date. This means partial scorer coverage on any given day does not bias the leaderboard — cells without a baseline snapshot inside the window are simply excluded. The same RPC powers the metro-overview "movement" rail in the Explorer and the standalone `/movers` page in the dashboard.

**Query parameters**

| Name        | Type   | Required | Default | Description                                                                                 |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------- |
| `days`      | int    |          | `30`    | Lookback window. Must be one of `7`, `30`, `90`, or `180`.                                  |
| `direction` | string |          | `up`    | `up` for biggest gainers, `down` for biggest decliners, or `all` to rank by absolute delta. |
| `metro`     | string |          |         | Metro slug filter (e.g. `sf`, `nyc`, `boston`). Omit for cross-metro results.               |
| `limit`     | int    |          | `25`    | Max results (1–100).                                                                        |

**Example**

```bash
curl "https://axiomlocus.io/api/top-movers?days=30&direction=up&metro=boston&limit=10"
```

**Response**

```json
{
  "window_days": 30,
  "direction": "up",
  "metro": "boston",
  "movers": [
    {
      "h3_index": "882a306665fffff",
      "metro_slug": "boston",
      "location_name": "Seaport District",
      "latest_composite": 61,
      "prior_composite": 38,
      "delta": 23,
      "latest_snapshot_date": "2026-04-29",
      "prior_snapshot_date": "2026-03-30"
    }
  ]
}
```

| Field                           | Type           | Description                                                                                         |
| ------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `window_days`                   | int            | Lookback window echoed from the request.                                                            |
| `direction`                     | string         | `up`, `down`, or `all` — echoed from the request.                                                   |
| `metro`                         | string \| null | Metro slug filter, or `null` when the call was cross-metro.                                         |
| `movers`                        | array          | Cells ranked by composite delta. Empty when the window has no eligible snapshot pairs yet.          |
| `movers[].h3_index`             | string         | H3 cell index.                                                                                      |
| `movers[].metro_slug`           | string         | Metro the cell belongs to.                                                                          |
| `movers[].location_name`        | string         | Neighborhood name.                                                                                  |
| `movers[].latest_composite`     | number         | Composite score 0–100 from the most recent snapshot.                                                |
| `movers[].prior_composite`      | number         | Composite score 0–100 from the freshest snapshot at or before the lookback boundary.                |
| `movers[].delta`                | number         | `latest_composite - prior_composite`. Positive when the cell is improving, negative when declining. |
| `movers[].latest_snapshot_date` | string         | Date of the latest snapshot (`YYYY-MM-DD`).                                                         |
| `movers[].prior_snapshot_date`  | string         | Date of the prior-side snapshot used as the baseline.                                               |


  Daily snapshots accumulate from the moment a cell is first scored, so newer metros may return an empty `movers` array on longer windows until enough history has built up. Use a shorter window (`days=7`) to surface activity earlier.


## `GET` `/api/schools` [#get-apischools]

Nearby school quality ratings (1-10 scale).

**Query parameters**

| Name     | Type  | Required | Default | Description      |
| -------- | ----- | -------- | ------- | ---------------- |
| `lat`    | float | ✓        |         | Latitude.        |
| `lng`    | float | ✓        |         | Longitude.       |
| `radius` | float |          | `2`     | Radius in miles. |
| `limit`  | int   |          | `10`    | Max results.     |

**Example**

```bash
curl "https://axiomlocus.io/api/schools?lat=37.7749&lng=-122.4194&radius=1"
```

**Response**

```json
{ "total": 5, "schools": [{ "name": "Lincoln Elementary", "rating": 8, "enrollment": 450 }] }
```

| Field                  | Type   | Description        |
| ---------------------- | ------ | ------------------ |
| `schools[].rating`     | number | Quality score 1-10 |
| `schools[].enrollment` | number | Student enrollment |

## `GET` `/api/life-sciences` [#get-apilife-sciences]

Clinical trials and FDA enforcement data by state or sponsor.

**Query parameters**

| Name      | Type   | Required | Default | Description                   |
| --------- | ------ | -------- | ------- | ----------------------------- |
| `state`   | string |          |         | US state name.                |
| `sponsor` | string |          |         | Sponsor name (partial match). |
| `type`    | string |          | `all`   | Filter: trials, fda, or all.  |
| `limit`   | int    |          | `50`    | Max results.                  |

**Example**

```bash
curl "https://axiomlocus.io/api/life-sciences?state=Massachusetts&type=trials&limit=10"
```

**Response**

```json
{ "trials": { "total": 10, "data": [{ "nct_id": "NCT05754281", "sponsor": "Joslin Diabetes Center" }] } }
```

| Field                   | Type   | Description                 |
| ----------------------- | ------ | --------------------------- |
| `trials.data[].nct_id`  | string | ClinicalTrials.gov trial ID |
| `trials.data[].sponsor` | string | Lead sponsor organization   |

## `GET` `/api/zoning` [#get-apizoning]

Zoning district rules — allowed uses, height limits, FAR, setbacks.

**Query parameters**

| Name       | Type   | Required | Default | Description                                              |
| ---------- | ------ | -------- | ------- | -------------------------------------------------------- |
| `metro`    | string | ✓        |         | Metro slug.                                              |
| `code`     | string |          |         | Specific district code.                                  |
| `category` | string |          |         | Filter: residential, commercial, industrial, mixed\_use. |

**Example**

```bash
curl "https://axiomlocus.io/api/zoning?metro=denver&category=commercial"
```

**Response**

```json
{ "metro": "denver", "total": 8, "districts": [{ "district_code": "C-MX-5", "max_height_ft": 65, "max_far": 3.0 }] }
```

| Field                       | Type   | Description                     |
| --------------------------- | ------ | ------------------------------- |
| `districts[].district_code` | string | Zoning designation code         |
| `districts[].max_height_ft` | number | Maximum building height in feet |
| `districts[].max_far`       | number | Floor area ratio                |

## `GET` `/api/port-risk` [#get-apiport-risk]

Surface upstream port disruption affecting a Locus metro's economic catchment. Twenty-two metros are mapped to their primary and secondary ports by trucking corridor (e.g. `phoenix` → Long Beach via I-10, `atlanta` → Savannah via I-16). When an inbound port shows elevated wait times in [Overwatch](/overwatch/api/disruptions), the row appears here with a `risk_level` of `watch`, `elevated`, or `severe`, derived from p90 wait, median wait, and trend direction. Returns an empty `risks` array when no upstream port is currently disrupted — the [PortRiskBadge](/locus/dashboard) on cell-detail panels uses that signal to hide itself.

Use this to flag CRE locations whose tenants depend on container imports (industrial, logistics, big-box retail) before a soft port closure shows up in occupancy or rent comps.

**Query parameters**

| Name    | Type   | Required | Default | Description                                        |
| ------- | ------ | -------- | ------- | -------------------------------------------------- |
| `metro` | string | ✓        |         | Metro slug (e.g. `houston`, `atlanta`, `chicago`). |

**Example**

```bash
curl "https://axiomlocus.io/api/port-risk?metro=atlanta"
```

**Response**

```json
{
  "metro": "atlanta",
  "risks": [
    {
      "port_slug": "savannah",
      "port_name": "Port of Savannah",
      "tier": "primary",
      "trucking_km": 400,
      "median_wait_hours": 18,
      "p90_wait_hours": 84,
      "vessel_count": 23,
      "trend_direction": "worsening",
      "trend_consecutive_periods": 3,
      "risk_level": "severe",
      "measured_at": "2026-04-29T00:00:00Z"
    }
  ]
}
```

| Field                               | Type   | Description                                                                                                                     |
| ----------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `metro`                             | string | Metro slug echoed from the request.                                                                                             |
| `risks`                             | array  | Active port-risk rows, ordered by `risk_level` then `p90_wait_hours` (highest first). Empty when no upstream port is disrupted. |
| `risks[].port_slug`                 | string | Stable port identifier (e.g. `savannah`, `long-beach`, `ny-nj`).                                                                |
| `risks[].port_name`                 | string | Human-readable port name.                                                                                                       |
| `risks[].tier`                      | string | `primary` or `secondary` — the port's role in the metro's catchment.                                                            |
| `risks[].trucking_km`               | number | Driving distance from port to metro centroid (km).                                                                              |
| `risks[].median_wait_hours`         | number | Median vessel wait time at the port over the measurement window.                                                                |
| `risks[].p90_wait_hours`            | number | 90th-percentile wait — the figure that drives most risk-level transitions.                                                      |
| `risks[].vessel_count`              | number | Vessels currently queued or anchored upstream.                                                                                  |
| `risks[].trend_direction`           | string | `worsening`, `stable`, or `improving`.                                                                                          |
| `risks[].trend_consecutive_periods` | number | Periods the trend has held — used to confirm sustained disruption vs. a single-day spike.                                       |
| `risks[].risk_level`                | string | `watch`, `elevated`, or `severe`.                                                                                               |
| `risks[].measured_at`               | string | ISO 8601 timestamp of the underlying Overwatch measurement.                                                                     |

## `GET` `/api/export` [#get-apiexport]


  Requires an authenticated Supabase session (the session cookie sent by the browser). This route does not accept 

  `Authorization: Bearer ...`

   or 

  `X-API-Key`

   headers.


Export scored location data as CSV or JSON. Requires a Team plan or higher (`bulk_export` entitlement).

**Query parameters**

| Name     | Type    | Required | Default | Description                                                                                                                                |
| -------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `metro`  | string  |          |         | Metro slug filter (e.g. `sf`, `nyc`).                                                                                                      |
| `format` | string  |          | `csv`   | `csv` or `json`.                                                                                                                           |
| `saved`  | boolean |          | `false` | When `true`, restricts the export to the caller's saved cells (the cells in their `monitored_locations` portfolio). Composes with `metro`. |
| `limit`  | int     |          | `1000`  | Max rows (5000 max).                                                                                                                       |

**Portfolio export (`saved=true`)**

Set `saved=true` to export only the cells the authenticated user has saved into their portfolio (their `monitored_locations`). This is the intended workflow for analysts who track a curated set of cells across metros and want a CSV/JSON snapshot of just those rows rather than a full-metro or platform-wide pull.

* The filter is applied as an `IN` over the caller's saved `h3_index` list, so the result respects ordering by `composite` (descending) and the `limit` cap.
* It composes with `metro` — combining `saved=true&metro=sf` returns only saved cells inside SF.
* If the user has no saved cells, the endpoint short-circuits to an empty payload (`200 OK`) without scanning `cell_scores`. CSV responses return an empty body; JSON responses return `{ "total": 0, "data": [] }`.
* The download filename is tagged `saved` (e.g. `axiom-locus-saved-2026-04-29.csv`) instead of the metro slug or `all`, so portfolio exports are easy to identify on disk.

**Examples**

Export all SF cells as CSV:

```bash
curl "https://axiomlocus.io/api/export?metro=sf&format=csv" \
  -H "Cookie: sb--auth-token="
```

Export the caller's saved cells (portfolio) as CSV:

```bash
curl "https://axiomlocus.io/api/export?saved=true&format=csv" \
  -H "Cookie: sb--auth-token="
```

Export the caller's saved cells inside one metro as JSON:

```bash
curl "https://axiomlocus.io/api/export?saved=true&metro=sf&format=json" \
  -H "Cookie: sb--auth-token="
```

**Response**

```csv
h3_index,metro_slug,location_name,composite,...
88283082e7fffff,sf,Mission District,74,...
```

## `GET` `/api/bids` [#get-apibids]

Search federal and government procurement opportunities sourced from SAM.gov. Filter by state, keyword, or NAICS code to find relevant contracts.

**Query parameters**

| Name      | Type   | Required | Default | Description                                                    |
| --------- | ------ | -------- | ------- | -------------------------------------------------------------- |
| `state`   | string |          |         | Two-letter state code (e.g. `TX`, `CA`).                       |
| `keyword` | string |          |         | Full-text search across title and description.                 |
| `naics`   | string |          |         | NAICS code filter (e.g. `236220` for commercial construction). |
| `type`    | string |          |         | Bid type (partial match).                                      |
| `active`  | string |          | `true`  | Set to `false` to include expired bids.                        |
| `limit`   | int    |          | `50`    | Max results (max 200).                                         |

**Example**

```bash
curl "https://axiomlocus.io/api/bids?state=TX&keyword=construction&limit=10"
```

**Response**

```json
{
  "state": "TX",
  "keyword": "construction",
  "count": 10,
  "bids": [
    {
      "notice_id": "SAM-2026-001234",
      "title": "Renovation of Federal Building, Houston TX",
      "type": "Solicitation",
      "agency": "General Services Administration",
      "posted_date": "2026-04-10",
      "response_deadline": "2026-05-15",
      "description": "Full interior renovation of the federal courthouse...",
      "naics_code": "236220",
      "place_of_performance_city": "Houston",
      "place_of_performance_state": "TX",
      "estimated_value": 4500000,
      "url": "https://sam.gov/opp/abc123",
      "set_aside_type": "Small Business"
    }
  ]
}
```

| Field                      | Type   | Description                                                       |
| -------------------------- | ------ | ----------------------------------------------------------------- |
| `count`                    | int    | Number of matching bids returned.                                 |
| `bids[].notice_id`         | string | SAM.gov notice identifier.                                        |
| `bids[].response_deadline` | string | Deadline for bid submissions.                                     |
| `bids[].naics_code`        | string | NAICS industry classification code.                               |
| `bids[].estimated_value`   | number | Estimated contract value in USD.                                  |
| `bids[].set_aside_type`    | string | Set-aside designation (e.g. `Small Business`, `8(a)`, `HUBZone`). |


# Enrichment (/locus/api/enrichment)



## `GET` `/api/v1/enrich` [#get-apiv1enrich]


  Requires Bearer token.


The enrich endpoint supports three query modes. Pass **one** of `address`/`lat`+`lng`, `company`, or `facility` to select the mode.

### Location enrichment [#location-enrichment]

Enrich a US address (or lat/lng pair) with scores, permits, commuter data, nearby amenities, and hazards.

**Query parameters**

| Name      | Type   | Required | Default   | Description                                                                                              |
| --------- | ------ | -------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `address` | string | ✓\*      |           | Full US street address to geocode and enrich.                                                            |
| `lat`     | float  | ✓\*      |           | Latitude (use instead of `address`).                                                                     |
| `lng`     | float  | ✓\*      |           | Longitude (use instead of `address`).                                                                    |
| `radius`  | float  |          | `1.0`     | Search radius in km (max 10).                                                                            |
| `profile` | string |          | `general` | Scoring profile: `general`, `qsr`, `self_storage`, `retail`, `office`, `data_center`, `industrial`.      |
| `include` | string |          | `all`     | Comma-separated sections: `scores`, `pois`, `permits`, `demographics`, `risk`. Use `all` for everything. |

\*Provide either `address` or both `lat` and `lng`.

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl "https://axiomlocus.io/api/v1/enrich?address=123+Market+St+San+Francisco+CA" \
      -H "Authorization: Bearer al_your_key_here"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://axiomlocus.io/api/v1/enrich",
        params={"address": "123 Market St, San Francisco, CA"},
        headers={"Authorization": "Bearer al_your_key_here"},
    )
    enriched = res.json()  # scores, permits, commuter profile, hazards, ...
    ```
  

  
    ```js
    const url = new URL("https://axiomlocus.io/api/v1/enrich");
    url.searchParams.set("address", "123 Market St, San Francisco, CA");

    const enriched = await fetch(url, {
      headers: { Authorization: "Bearer al_your_key_here" },
    }).then((r) => r.json());
    ```
  


**Response**

```json
{
  "location": {
    "lat": 37.7935,
    "lng": -122.3958,
    "h3_index": "882a100d63fffff",
    "metro": "sf",
    "address": "123 Market St, San Francisco, CA 94105"
  },
  "scores": {
    "composite": 76.2,
    "profile": "general",
    "confidence": 0.94,
    "groups": {
      "businessVitality": { "score": 82 },
      "populationMomentum": { "score": 71 },
      "demographics": { "score": 80 },
      "economicStrength": { "score": 75 },
      "developmentPipeline": { "score": 69 },
      "accessibility": { "score": 88 },
      "safetyEnvironment": { "score": 62 },
      "amenityDemand": { "score": 79 }
    }
  },
  "permit_activity": {
    "count_12m": 34,
    "momentum": "accelerating",
    "dominant_type": "renovation",
    "predicted_next": "new_construction",
    "predicted_probability": 0.72
  },
  "crime_safety": {
    "level": "moderate",
    "severity_score": 42,
    "incidents_90d": 18
  },
  "commuter_profile": {
    "total_jobs": 14200,
    "high_earners_pct": 38.5,
    "top_sectors": ["Professional Services", "Information", "Finance"]
  },
  "nearby": {
    "schools": 5,
    "avg_school_quality": 7.2,
    "pois": 120,
    "clinical_trials": 8
  },
  "hazards": [
    { "type": "epa_non_compliant_facility", "value": "ABC Chemical Corp" }
  ],
  "neighborhood": "Financial District"
}
```

| Field              | Type   | Description                                                                 |
| ------------------ | ------ | --------------------------------------------------------------------------- |
| `location`         | object | Geocoded coordinates, H3 cell index, and metro.                             |
| `scores`           | object | Full scoring breakdown with composite and all 8 signal groups.              |
| `permit_activity`  | object | 12-month permit count, momentum, dominant type, and next-permit prediction. |
| `crime_safety`     | object | Safety level, severity score, and recent incident count.                    |
| `commuter_profile` | object | LEHD-based commuter data: total jobs, high-earner percentage, top sectors.  |
| `nearby`           | object | Counts of nearby schools, POIs, and clinical trials.                        |
| `hazards`          | array  | Environmental hazards (e.g. EPA non-compliant facilities).                  |
| `neighborhood`     | string | Resolved neighborhood name.                                                 |

***

### Company enrichment [#company-enrichment]

Enrich a company name with supply chain fragility scoring, FDA compliance events, and predictive hazard analysis.

**Query parameters**

| Name      | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `company` | string | ✓        | Company name to look up. |

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl "https://axiomlocus.io/api/v1/enrich?company=Pfizer" \
      -H "Authorization: Bearer al_your_key_here"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://axiomlocus.io/api/v1/enrich",
        params={"company": "Pfizer"},
        headers={"Authorization": "Bearer al_your_key_here"},
    )
    company = res.json()  # fragility_score, warning_letters, facilities, ...
    ```
  

  
    ```js
    const url = new URL("https://axiomlocus.io/api/v1/enrich");
    url.searchParams.set("company", "Pfizer");

    const company = await fetch(url, {
      headers: { Authorization: "Bearer al_your_key_here" },
    }).then((r) => r.json());
    ```
  


**Response**

```json
{
  "company": "Pfizer",
  "fragility_score": 32,
  "risk_level": "low",
  "component_scores": {
    "regulatory": 28,
    "supply_chain": 35,
    "geographic_concentration": 30
  },
  "warning_letters": 2,
  "drug_shortages": 1,
  "hazard_predictions": [
    { "event": "shortage_escalation", "probability_90d": 0.12 },
    { "event": "warning_letter", "probability_90d": 0.08 }
  ],
  "facilities": [
    {
      "name": "Pfizer McPherson Plant",
      "lat": 38.371,
      "lng": -97.664,
      "sources": ["fda", "epa", "osha"],
      "compliance_events": 4,
      "entity_type": "manufacturing"
    }
  ]
}
```

| Field                | Type   | Description                                                                     |
| -------------------- | ------ | ------------------------------------------------------------------------------- |
| `fragility_score`    | number | Supply chain fragility index (0–100, lower is more resilient).                  |
| `risk_level`         | string | Risk classification: `low`, `moderate`, `high`, or `critical`.                  |
| `component_scores`   | object | Breakdown by regulatory, supply chain, and geographic concentration risk.       |
| `warning_letters`    | number | Count of FDA warning letters.                                                   |
| `drug_shortages`     | number | Count of active drug shortages linked to this company.                          |
| `hazard_predictions` | array  | 90-day event probability forecasts derived from lead-lag correlation models.    |
| `facilities`         | array  | Known facilities with cross-referenced compliance data from FDA, EPA, and OSHA. |

***

### Facility enrichment [#facility-enrichment]

Enrich a specific facility with OSHA inspection history, EPA compliance status, and FDA enforcement actions.

**Query parameters**

| Name       | Type   | Required | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `facility` | string | ✓        | Facility name to look up. |

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl "https://axiomlocus.io/api/v1/enrich?facility=Pfizer+McPherson+Plant" \
      -H "Authorization: Bearer al_your_key_here"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://axiomlocus.io/api/v1/enrich",
        params={"facility": "Pfizer McPherson Plant"},
        headers={"Authorization": "Bearer al_your_key_here"},
    )
    facility = res.json()  # osha, epa, fda compliance records
    ```
  

  
    ```js
    const url = new URL("https://axiomlocus.io/api/v1/enrich");
    url.searchParams.set("facility", "Pfizer McPherson Plant");

    const facility = await fetch(url, {
      headers: { Authorization: "Bearer al_your_key_here" },
    }).then((r) => r.json());
    ```
  


**Response**

```json
{
  "facility": "Pfizer McPherson Plant",
  "location": { "lat": 38.371, "lng": -97.664 },
  "entity_type": "manufacturing",
  "source_count": 3,
  "compliance_events": 4,
  "osha": {
    "total": 2,
    "recent": [
      {
        "activity_nr": "1234567",
        "name": "Pfizer McPherson",
        "violations": 1,
        "penalty": 12500,
        "date": "2025-09-15"
      }
    ]
  },
  "epa": [
    {
      "id": "KSD001234567",
      "name": "Pfizer McPherson Facility",
      "compliance": "in_compliance",
      "violations": 0,
      "last_inspection": "2025-11-20"
    }
  ],
  "fda": {
    "total": 2,
    "recent": [
      {
        "id": "evt-abc123",
        "type": "inspection",
        "classification": "VAI",
        "date": "2025-08-10"
      }
    ]
  }
}
```

| Field               | Type   | Description                                                                |
| ------------------- | ------ | -------------------------------------------------------------------------- |
| `entity_type`       | string | Facility classification (e.g. `manufacturing`, `warehouse`, `laboratory`). |
| `source_count`      | number | Number of data sources with records for this facility.                     |
| `compliance_events` | number | Total compliance events across all sources.                                |
| `osha`              | object | OSHA inspection history with violation counts and penalties.               |
| `epa`               | array  | EPA facility compliance status and inspection dates.                       |
| `fda`               | object | FDA enforcement actions and inspection classifications.                    |


# Custom formulas (/locus/api/formulas)



Custom formulas let you adjust the relative weight of each signal group in the Locus composite score. Instead of using a fixed [scoring profile](/locus/scoring-conventions#scoring-profiles), you define your own weighting — emphasizing the signals that matter most for your asset class and investment thesis.

Formulas are versioned and can be applied to [portfolios](/locus/api/portfolios). When a portfolio has an active formula, all location scores are computed with the formula weights instead of the default composite.


  The custom formula endpoints described below are planned and are not currently
  mounted in the Axiom Locus app route tree. In particular, `/api/v1/locus/formulas`
  and its `/compare` subroute do not currently exist; do not send these requests
  to production until the routes are released.


## How weights work [#how-weights-work]

Each formula defines a weight for the eight Locus signal groups:

| Signal group         | Key                    | Default weight |
| -------------------- | ---------------------- | -------------- |
| Business vitality    | `business_vitality`    | 1.0            |
| Population momentum  | `population_momentum`  | 1.0            |
| Demographics         | `demographics`         | 1.0            |
| Economic strength    | `economic_strength`    | 1.0            |
| Development pipeline | `development_pipeline` | 1.0            |
| Accessibility        | `accessibility`        | 1.0            |
| Safety & environment | `safety_environment`   | 1.0            |
| Amenity demand       | `amenity_demand`       | 1.0            |

Weights are normalized so they sum to 1.0 before scoring. A weight of `2.0` on `business_vitality` with `1.0` on everything else means business vitality contributes roughly 22% of the final score instead of the default 12.5%.

## `GET` `/api/v1/locus/formulas` [#get-apiv1locusformulas]


  Requires session authentication.


List all scoring formulas available to you. This includes system-provided formulas and your custom formulas.

**Parameters**

| Name          | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `asset_class` | string |          | Filter by asset class (e.g. `qsr`, `retail`, `office`). |

**Response**

```json
{
  "formulas": [
    {
      "id": "f_sys_qsr_v1",
      "name": "QSR Standard",
      "asset_class": "qsr",
      "version": 1,
      "is_system": true,
      "weights_json": {
        "business_vitality": 2.0,
        "population_momentum": 1.5,
        "demographics": 1.5,
        "economic_strength": 1.0,
        "development_pipeline": 0.5,
        "accessibility": 1.5,
        "safety_environment": 1.0,
        "amenity_demand": 1.0
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "f_custom_abc",
      "name": "Drive-through optimized",
      "asset_class": "qsr",
      "version": 2,
      "is_system": false,
      "weights_json": {
        "business_vitality": 1.0,
        "population_momentum": 1.0,
        "demographics": 2.0,
        "economic_strength": 1.0,
        "development_pipeline": 0.5,
        "accessibility": 3.0,
        "safety_environment": 1.0,
        "amenity_demand": 0.5
      },
      "created_at": "2026-03-15T09:00:00Z",
      "updated_at": "2026-04-10T14:00:00Z"
    }
  ]
}
```

| Field          | Type    | Description                                                           |
| -------------- | ------- | --------------------------------------------------------------------- |
| `is_system`    | boolean | `true` for Locus-provided formulas, `false` for your custom formulas. |
| `weights_json` | object  | Signal group weights. Normalized to sum to 1.0 when applied.          |
| `version`      | int     | Formula version number.                                               |

**Example**

```bash
curl https://axiomlocus.io/api/v1/locus/formulas?asset_class=qsr \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## `POST` `/api/v1/locus/formulas` [#post-apiv1locusformulas]


  Requires session authentication.


Create a custom scoring formula. If you omit `weights_json`, Locus uses the default weights for the specified asset class.

**Parameters**

| Name           | Type   | Required | Description                                                               |
| -------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `name`         | string | ✓        | Formula name.                                                             |
| `asset_class`  | string | ✓        | Asset class this formula is designed for.                                 |
| `version`      | number |          | Version number (default 1).                                               |
| `weights_json` | object |          | Custom weights. Each key is a signal group, value is the relative weight. |

**Example**

```bash
curl -X POST https://axiomlocus.io/api/v1/locus/formulas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Drive-through optimized",
    "asset_class": "qsr",
    "weights_json": {
      "business_vitality": 1.0,
      "demographics": 2.0,
      "accessibility": 3.0,
      "amenity_demand": 0.5
    }
  }'
```

**Response** (HTTP 201)

```json
{
  "formula": {
    "id": "f_custom_abc",
    "name": "Drive-through optimized",
    "asset_class": "qsr",
    "version": 1,
    "is_system": false,
    "weights_json": {
      "business_vitality": 1.0,
      "population_momentum": 1.0,
      "demographics": 2.0,
      "economic_strength": 1.0,
      "development_pipeline": 1.0,
      "accessibility": 3.0,
      "safety_environment": 1.0,
      "amenity_demand": 0.5
    },
    "created_at": "2026-04-20T12:00:00Z",
    "updated_at": "2026-04-20T12:00:00Z"
  }
}
```


  Any signal group you omit from `weights_json` defaults to `1.0`. Weights are normalized before scoring so only the ratios between groups matter, not the absolute values.


***

## Compare formulas [#compare-formulas]

### `GET` `/api/v1/locus/formulas/compare` [#get-apiv1locusformulascompare]


  Requires session authentication.


Score a single H3 cell with multiple formulas side-by-side. Use this to see how different weightings affect the composite score for a specific location before applying a formula to your portfolio.

**Parameters**

| Name          | Type   | Required | Description                             |
| ------------- | ------ | -------- | --------------------------------------- |
| `h3_index`    | string | ✓        | H3 cell id to score.                    |
| `profile`     | string |          | Scoring profile (default `general`).    |
| `formula_ids` | string | ✓        | Comma-separated formula ids to compare. |

**Response**

```json
{
  "h3_index": "882a100d63fffff",
  "profile": "general",
  "base_composite": 72.0,
  "comparisons": [
    {
      "formula_id": "f_sys_qsr_v1",
      "name": "QSR Standard",
      "asset_class": "qsr",
      "version": 1,
      "is_system": true,
      "score": 76.3,
      "delta_from_base": 4.3
    },
    {
      "formula_id": "f_custom_abc",
      "name": "Drive-through optimized",
      "asset_class": "qsr",
      "version": 2,
      "is_system": false,
      "score": 79.1,
      "delta_from_base": 7.1
    }
  ]
}
```

| Field                           | Type  | Description                                                                                    |
| ------------------------------- | ----- | ---------------------------------------------------------------------------------------------- |
| `base_composite`                | float | Default composite score without any formula.                                                   |
| `comparisons[].score`           | float | Composite score using this formula's weights.                                                  |
| `comparisons[].delta_from_base` | float | Difference from the default composite. Positive means the formula scores this location higher. |

**Example**

```bash
curl "https://axiomlocus.io/api/v1/locus/formulas/compare?h3_index=882a100d63fffff&formula_ids=f_sys_qsr_v1,f_custom_abc" \
  -H "Authorization: Bearer YOUR_TOKEN"
```


# Integrations (/locus/api/integrations)



Push enriched Locus intelligence into your CRM, ticketing system, or automation platform. Each integration enriches records with composite scores, safety levels, permit activity, and neighborhood context.

All integration endpoints share the same lifecycle:

1. **Connect** — `POST` with credentials to verify and save the integration.
2. **Check status** — `GET` to see whether the integration is active.
3. **Disconnect** — `DELETE` to deactivate.

You can optionally include an `enrich` object in the `POST` body to trigger immediate enrichment of a specific record.

***

## `POST` `/api/v1/integrations/salesforce` [#post-apiv1integrationssalesforce]


  Requires Bearer token.


Push enriched location data to Salesforce CRM.

**Request body**

```json
{
  "instance_url": "https://yourorg.my.salesforce.com",
  "access_token": "00D...",
  "refresh_token": "5Aep...",
  "object_type": "Lead",
  "enrich": {
    "record_id": "00Q5f00000XXXXX",
    "address": "123 Market St, San Francisco, CA"
  }
}
```

| Field           | Type   | Required | Description                                                    |
| --------------- | ------ | -------- | -------------------------------------------------------------- |
| `instance_url`  | string | ✓        | Salesforce instance URL (`*.salesforce.com` or `*.force.com`). |
| `access_token`  | string | ✓        | OAuth access token.                                            |
| `refresh_token` | string | ✓        | OAuth refresh token.                                           |
| `object_type`   | string | ✓        | Target object: `Lead`, `Account`, `Opportunity`, or `Custom`.  |
| `enrich`        | object |          | Optional. Enrich a record immediately on setup.                |

**Enrichment fields pushed to Salesforce:**

| Salesforce field           | Description                           |
| -------------------------- | ------------------------------------- |
| `Axiom_Score__c`           | Composite score (0–100).              |
| `Axiom_Safety_Level__c`    | Safety assessment level.              |
| `Axiom_Permit_Momentum__c` | Permit activity momentum indicator.   |
| `Axiom_Fragility_Score__c` | Supply chain fragility score.         |
| `Axiom_Profile__c`         | Scoring profile used.                 |
| `Axiom_Permits_12m__c`     | Permit count over the last 12 months. |
| `Axiom_Neighborhood__c`    | Resolved neighborhood name.           |
| `Axiom_Enriched_At__c`     | Timestamp of last enrichment.         |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/salesforce" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "instance_url": "https://yourorg.my.salesforce.com",
    "access_token": "00D...",
    "refresh_token": "5Aep...",
    "object_type": "Lead"
  }'
```

***

## `POST` `/api/v1/integrations/hubspot` [#post-apiv1integrationshubspot]


  Requires Bearer token.


Push enriched data to HubSpot CRM contacts, companies, or deals.

**Request body**

```json
{
  "access_token": "pat-na1-...",
  "object_type": "contacts",
  "enrich": {
    "record_id": "123456",
    "address": "456 Broadway, New York, NY"
  }
}
```

| Field           | Type   | Required | Description                                                                            |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `access_token`  | string | ✓        | OAuth token or private app token.                                                      |
| `refresh_token` | string |          | Required for OAuth flows. Omit for private app tokens.                                 |
| `object_type`   | string | ✓        | Target object: `contacts`, `companies`, or `deals`.                                    |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`. |

**Enrichment properties pushed to HubSpot:**

`axiom_score`, `axiom_safety`, `axiom_permit_activity`, `axiom_fragility`, `axiom_profile`, `axiom_permits_12m`, `axiom_neighborhood`, `axiom_enriched_at`

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "access_token": "pat-na1-abc123",
    "object_type": "companies"
  }'
```

***

## `POST` `/api/v1/integrations/dynamics` [#post-apiv1integrationsdynamics]


  Requires Bearer token.


Push enriched data to Microsoft Dynamics 365 entities via the Dataverse Web API.

**Request body**

```json
{
  "tenant_id": "your-azure-tenant-id",
  "client_id": "your-app-registration-id",
  "client_secret": "your-client-secret",
  "resource_url": "https://yourorg.crm.dynamics.com",
  "entity_type": "lead"
}
```

| Field           | Type   | Required | Description                                                                            |
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `tenant_id`     | string | ✓        | Azure AD tenant ID.                                                                    |
| `client_id`     | string | ✓        | App registration client ID.                                                            |
| `client_secret` | string | ✓        | App registration client secret.                                                        |
| `resource_url`  | string | ✓        | Dynamics instance URL (must end in `.dynamics.com` or `.crm.dynamics.com`).            |
| `entity_type`   | string | ✓        | Dynamics entity logical name (e.g. `lead`, `account`, `opportunity`).                  |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`. |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/dynamics" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "tenant_id": "abc-123",
    "client_id": "def-456",
    "client_secret": "secret",
    "resource_url": "https://yourorg.crm.dynamics.com",
    "entity_type": "lead"
  }'
```

***

## `POST` `/api/v1/integrations/zoho` [#post-apiv1integrationszoho]


  Requires Bearer token.


Push enriched data to Zoho CRM modules.

**Request body**

```json
{
  "access_token": "1000.abc123...",
  "refresh_token": "1000.def456...",
  "module": "Leads",
  "enrich": {
    "record_id": "5234876000001234567",
    "address": "789 Pine St, Denver, CO"
  }
}
```

| Field           | Type   | Required | Description                                                                                     |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `access_token`  | string | ✓        | Zoho OAuth access token.                                                                        |
| `refresh_token` | string | ✓        | Zoho OAuth refresh token.                                                                       |
| `api_domain`    | string |          | API domain. Defaults to `https://www.zohoapis.com`. Also accepts `.zoho.com` or `.zohoapis.eu`. |
| `module`        | string |          | Target module: `Leads`, `Accounts`, `Contacts`, or `Deals`. Defaults to `Leads`.                |
| `enrich`        | object |          | Optional. Enrich a record immediately. Include `record_id` and `address` or `company`.          |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/zoho" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "access_token": "1000.abc123...",
    "refresh_token": "1000.def456...",
    "module": "Accounts"
  }'
```

***

## `POST` `/api/v1/integrations/zendesk` [#post-apiv1integrationszendesk]


  Requires Bearer token.


Enrich Zendesk tickets with location intelligence. Adds an internal note with scoring data and sets custom ticket fields.

**Request body**

```json
{
  "subdomain": "mycompany",
  "api_token": "your-zendesk-api-token",
  "email": "admin@mycompany.com",
  "enrich": {
    "ticket_id": "12345",
    "address": "100 Oak Ave, Austin, TX"
  }
}
```

| Field       | Type   | Required | Description                                                                             |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `subdomain` | string | ✓        | Your Zendesk subdomain (e.g. `mycompany` for `mycompany.zendesk.com`).                  |
| `api_token` | string | ✓        | Zendesk API token.                                                                      |
| `email`     | string | ✓        | Admin email address for authentication.                                                 |
| `enrich`    | object |          | Optional. Enrich a ticket immediately. Include `ticket_id` and `address` or `facility`. |

**Enrichment behavior:**

* Adds a **private internal note** on the ticket with composite score, safety level, and neighborhood data.
* Sets custom ticket fields: `axiom_score` and `axiom_safety`.

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/zendesk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "subdomain": "mycompany",
    "api_token": "abc123",
    "email": "admin@mycompany.com"
  }'
```

***

## `POST` `/api/v1/integrations/zapier` [#post-apiv1integrationszapier]


  Requires Bearer token.


Forward Locus events to any webhook URL. Works with Zapier, Make, n8n, or any platform that accepts webhooks.

**Request body**

```json
{
  "webhook_url": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "trigger_events": ["score_change", "permit_surge", "fragility_spike"],
  "name": "My Zapier Zap"
}
```

| Field            | Type   | Required | Description                                                                                    |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `webhook_url`    | string | ✓        | HTTPS webhook URL to receive events.                                                           |
| `trigger_events` | array  |          | Event types to forward. Defaults to all.                                                       |
| `format`         | string |          | Payload format: `json` (default) or `form` (form-urlencoded).                                  |
| `name`           | string |          | Friendly name. Defaults to `Zapier Webhook`.                                                   |
| `enrich`         | object |          | Optional. Push an enrichment payload immediately. Include `address`, `company`, or `facility`. |

**Available trigger events:**

| Event              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `hotspot_detected` | A new permit or activity hotspot appears.          |
| `fragility_spike`  | Supply chain fragility score spikes for a company. |
| `rule_change`      | Zoning or regulatory rule change detected.         |
| `permit_surge`     | Permit filing rate exceeds normal levels.          |
| `score_change`     | Composite score changes significantly.             |
| `shortage_alert`   | Drug shortage or supply disruption detected.       |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/integrations/zapier" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{
    "webhook_url": "https://hooks.zapier.com/hooks/catch/123/abc/",
    "trigger_events": ["permit_surge", "score_change"]
  }'
```

***

## Managing integrations [#managing-integrations]

All integration endpoints support `GET` and `DELETE` methods for status checks and deactivation.

### Check status [#check-status]

```bash
curl "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Authorization: Bearer al_your_key_here"
```

```json
{
  "configured": true,
  "object_type": "contacts",
  "active": true,
  "last_sync_at": "2026-04-19T10:30:00Z"
}
```

### Deactivate [#deactivate]

```bash
curl -X DELETE "https://axiomlocus.io/api/v1/integrations/hubspot" \
  -H "Authorization: Bearer al_your_key_here"
```

***

## `POST` `/api/v1/keys` [#post-apiv1keys]


  Requires Bearer token.


Create and manage API keys programmatically. Keys are prefixed with `al_` and can be scoped to specific endpoints.

**Request body**

```json
{
  "action": "create",
  "name": "Production Key",
  "scopes": ["score", "enrich", "permits"]
}
```

| Field    | Type   | Required | Default | Description                                      |
| -------- | ------ | -------- | ------- | ------------------------------------------------ |
| `action` | string | ✓        |         | Action: `create`, `list`, or `revoke`.           |
| `name`   | string |          |         | Human-readable key name (required for `create`). |
| `scopes` | array  |          |         | Endpoint scopes. Omit for full access.           |
| `key_id` | string |          |         | Key ID to revoke (required for `revoke` action). |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{"action":"create","name":"Production Key","scopes":["score","enrich"]}'
```

**Response**

```json
{
  "key": {
    "id": "key_abc123",
    "name": "Production Key",
    "token": "al_live_abc123def456ghi789",
    "scopes": ["score", "enrich"],
    "created_at": "2026-03-31T12:00:00Z"
  }
}
```

| Field        | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| `key.id`     | string | Key identifier for management operations.   |
| `key.token`  | string | Full API key (only shown once on creation). |
| `key.scopes` | array  | Endpoint scopes this key can access.        |


# Location Data (/locus/api/location-data)



## `GET` `/api/pois` [#get-apipois]

Nearby points of interest with ratings and photos.

**Query parameters**

| Name     | Type  | Required | Default | Description                      |
| -------- | ----- | -------- | ------- | -------------------------------- |
| `lat`    | float | ✓        |         | Latitude.                        |
| `lng`    | float | ✓        |         | Longitude.                       |
| `radius` | float |          | `0.5`   | Radius in km (max 10).           |
| `limit`  | int   |          | `50`    | Max results to return (max 200). |

**Example**

```bash
curl "https://axiomlocus.io/api/pois?lat=37.7749&lng=-122.4194&radius=0.5"
```

**Response**

```json
{
  "pois": [
    {
      "id": "abc123",
      "name": "Blue Bottle Coffee",
      "primary_type": "cafe",
      "rating": 4.5,
      "review_count": 342,
      "photo_reference": "Aap_uE...",
      "distance_m": 120
    }
  ]
}
```

| Field                    | Type   | Description                                     |
| ------------------------ | ------ | ----------------------------------------------- |
| `pois`                   | array  | Array of nearby point-of-interest objects.      |
| `pois[].id`              | string | Unique POI identifier.                          |
| `pois[].name`            | string | Business name.                                  |
| `pois[].primary_type`    | string | Business type category.                         |
| `pois[].rating`          | float  | Average rating (0-5).                           |
| `pois[].review_count`    | int    | Total number of reviews.                        |
| `pois[].photo_reference` | string | Photo reference for use with /api/places-photo. |
| `pois[].distance_m`      | float  | Distance from query point in meters.            |

## `GET` `/api/permits` [#get-apipermits]

Building permits near a location with value aggregation.

**Query parameters**

| Name     | Type  | Required | Default | Description            |
| -------- | ----- | -------- | ------- | ---------------------- |
| `lat`    | float | ✓        |         | Latitude.              |
| `lng`    | float | ✓        |         | Longitude.             |
| `radius` | float |          | `1.0`   | Radius in km (max 10). |

**Example**

```bash
curl "https://axiomlocus.io/api/permits?lat=37.7749&lng=-122.4194"
```

**Response**

```json
{
  "total_permits": 47,
  "total_value": 12500000,
  "by_type": {
    "new_construction": 12,
    "renovation": 28,
    "demolition": 7
  },
  "permits": [
    {
      "id": "P-2025-1234",
      "permit_type": "new_construction",
      "status": "issued",
      "address": "123 Market St",
      "estimated_cost": 2500000,
      "issue_date": "2025-11-15"
    }
  ]
}
```

| Field           | Type   | Description                                |
| --------------- | ------ | ------------------------------------------ |
| `total_permits` | int    | Total number of permits in the radius.     |
| `total_value`   | float  | Sum of estimated\_cost across all permits. |
| `by_type`       | object | Permit count grouped by type.              |
| `permits`       | array  | Up to 10 most recent permit records.       |

## `GET` `/api/traffic` [#get-apitraffic]

Real-time traffic flow data.

**Query parameters**

| Name  | Type  | Required | Default | Description |
| ----- | ----- | -------- | ------- | ----------- |
| `lat` | float | ✓        |         | Latitude.   |
| `lng` | float | ✓        |         | Longitude.  |

**Example**

```bash
curl "https://axiomlocus.io/api/traffic?lat=37.7749&lng=-122.4194"
```

**Response**

```json
{
  "current_speed": 28,
  "free_flow_speed": 45,
  "congestion_ratio": 0.62,
  "congestion_level": "moderate",
  "road_category": "arterial"
}
```

| Field              | Type   | Description                                |
| ------------------ | ------ | ------------------------------------------ |
| `current_speed`    | int    | Current speed in mph.                      |
| `free_flow_speed`  | int    | Free-flow speed in mph (no traffic).       |
| `congestion_ratio` | float  | Ratio of current to free-flow speed (0-1). |
| `congestion_level` | string | Human-readable congestion level.           |
| `road_category`    | string | Road type classification.                  |

## `GET` `/api/jobs` [#get-apijobs]

Local job market data.

**Query parameters**

| Name  | Type  | Required | Default | Description |
| ----- | ----- | -------- | ------- | ----------- |
| `lat` | float | ✓        |         | Latitude.   |
| `lng` | float | ✓        |         | Longitude.  |

**Example**

```bash
curl "https://axiomlocus.io/api/jobs?lat=37.7749&lng=-122.4194"
```

**Response**

```json
{
  "total_postings": 1243,
  "avg_salary": 95000,
  "top_categories": [
    { "name": "IT Jobs", "count": 412 },
    { "name": "Engineering", "count": 198 }
  ],
  "top_companies": [
    { "name": "Salesforce", "count": 87 },
    { "name": "Google", "count": 64 }
  ]
}
```

| Field            | Type  | Description                                   |
| ---------------- | ----- | --------------------------------------------- |
| `total_postings` | int   | Total active job postings near this location. |
| `avg_salary`     | float | Average listed salary in USD.                 |
| `top_categories` | array | Top job categories by count.                  |
| `top_companies`  | array | Top hiring companies by posting count.        |

## `GET` `/api/cells` [#get-apicells]

H3 heatmap cells for a metro area.

**Query parameters**

| Name    | Type   | Required | Default | Description                                   |
| ------- | ------ | -------- | ------- | --------------------------------------------- |
| `metro` | string |          | `sf`    | Metro slug (e.g. sf, nyc, la, chi, mia, atx). |

**Example**

```bash
curl "https://axiomlocus.io/api/cells?metro=sf"
```

**Response**

```json
{
  "cells": [
    {
      "h3_index": "882a100d63fffff",
      "priority": 0.85,
      "center_lat": 37.7749,
      "center_lng": -122.4194
    }
  ]
}
```

| Field                | Type   | Description                                 |
| -------------------- | ------ | ------------------------------------------- |
| `cells`              | array  | Array of H3 hexagonal cells.                |
| `cells[].h3_index`   | string | H3 hex index at resolution 8.               |
| `cells[].priority`   | float  | Priority score for heatmap rendering (0-1). |
| `cells[].center_lat` | float  | Latitude of the hex center.                 |
| `cells[].center_lng` | float  | Longitude of the hex center.                |

## `GET` `/api/neighborhood-score` [#get-apineighborhood-score]

Aggregated scores for an H3 neighborhood (resolution-7 parent cell). Returns the average of all resolution-8 child cells within the neighborhood. Fast, cached response.

**Query parameters**

| Name      | Type   | Required | Default   | Description                                                                              |
| --------- | ------ | -------- | --------- | ---------------------------------------------------------------------------------------- |
| `h3Index` | string | ✓        |           | Resolution-8 H3 cell index. The endpoint automatically resolves the parent neighborhood. |
| `profile` | string |          | `general` | Scoring profile.                                                                         |

**Example**

```bash
curl "https://axiomlocus.io/api/neighborhood-score?h3Index=882a100d63fffff&profile=general"
```

**Response**

```json
{
  "composite": 68.4,
  "confidence": 0.89,
  "scoreLow": 62.1,
  "scoreHigh": 74.7,
  "coverageLevel": "high",
  "groups": {
    "businessVitality": { "score": 72, "confidence": 0.91 },
    "populationMomentum": { "score": 65, "confidence": 0.87 },
    "demographics": { "score": 71, "confidence": 0.93 },
    "economicStrength": { "score": 67, "confidence": 0.88 },
    "developmentPipeline": { "score": 60, "confidence": 0.82 },
    "accessibility": { "score": 78, "confidence": 0.95 },
    "safetyEnvironment": { "score": 55, "confidence": 0.84 },
    "amenityDemand": { "score": 73, "confidence": 0.90 }
  },
  "cellCount": 7,
  "neighborhoodH3": "872a100d6ffffff",
  "profile": "general"
}
```

| Field                    | Type   | Description                                      |
| ------------------------ | ------ | ------------------------------------------------ |
| `composite`              | float  | Average composite score across the neighborhood. |
| `scoreLow` / `scoreHigh` | float  | Confidence interval bounds.                      |
| `coverageLevel`          | string | Data coverage: `high`, `medium`, or `low`.       |
| `cellCount`              | int    | Number of resolution-8 cells averaged.           |
| `neighborhoodH3`         | string | Resolution-7 parent H3 index.                    |

## `GET` `/api/neighborhoods/score` [#get-apineighborhoodsscore]

Score a named neighborhood by running the full scoring engine across cells within its boundary. More detailed than `/api/neighborhood-score` — includes tier classification, summary text, and the neighborhood boundary geometry.

**Query parameters**

| Name         | Type   | Required | Default   | Description                                      |
| ------------ | ------ | -------- | --------- | ------------------------------------------------ |
| `metro_slug` | string | ✓        |           | Metro slug (e.g. `sf`, `nyc`).                   |
| `name`       | string | ✓        |           | Neighborhood name (e.g. `Hayes Valley`, `SoMa`). |
| `profile`    | string |          | `general` | Scoring profile.                                 |

**Example**

```bash
curl "https://axiomlocus.io/api/neighborhoods/score?metro_slug=sf&name=Hayes+Valley"
```

**Response**

```json
{
  "neighborhood": {
    "name": "Hayes Valley",
    "metro_slug": "sf",
    "cell_count": 14,
    "sampled_cells": 10,
    "population": 8200,
    "source": "census_places"
  },
  "score": {
    "composite": 74,
    "tier": "A",
    "tierDescription": "Strong fundamentals with active development signals",
    "summary": "Hayes Valley scores well for business vitality and accessibility, driven by dense retail corridors and strong transit access.",
    "confidence": 0.91,
    "scoreLow": 68,
    "scoreHigh": 80,
    "coverageLevel": "high",
    "sourcesUsed": 18,
    "sourcesTotal": 22,
    "profile": "general",
    "groups": {
      "businessVitality": { "score": 82, "tier": "A", "confidence": 0.93 },
      "accessibility": { "score": 88, "tier": "A+", "confidence": 0.96 }
    }
  }
}
```

| Field                        | Type   | Description                                                                    |
| ---------------------------- | ------ | ------------------------------------------------------------------------------ |
| `neighborhood.cell_count`    | int    | Total H3 cells in the boundary.                                                |
| `neighborhood.sampled_cells` | int    | Number of cells actually scored (up to 10).                                    |
| `score.tier`                 | string | Letter grade: `A+`, `A`, `B+`, `B`, `C`, `D`, `F`.                             |
| `score.summary`              | string | AI-generated narrative summary of the neighborhood's strengths and weaknesses. |
| `score.groups`               | object | Per-group scores with tier and confidence.                                     |


# ML Exports (/locus/api/ml-exports)



## `GET` `/api/exports/croissant` [#get-apiexportscroissant]


  Requires Bearer token.


ML-ready dataset metadata in Croissant (schema.org/Dataset) format for use with TensorFlow Datasets, Hugging Face, and other ML frameworks.

**Query parameters**

| Name      | Type   | Required | Default | Description                                               |
| --------- | ------ | -------- | ------- | --------------------------------------------------------- |
| `dataset` | string | ✓        |         | Dataset name: scores, permits, pois, crime, demographics. |
| `metro`   | string |          |         | Metro slug filter.                                        |

**Example**

```bash
curl "https://axiomlocus.io/api/exports/croissant?dataset=scores&metro=sf" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{
  "@context": "https://schema.org",
  "@type": "Dataset",
  "name": "axiom-locus-scores-sf",
  "description": "Location intelligence scores for San Francisco metro area",
  "license": "https://axiomlocus.io/terms",
  "distribution": [
    {
      "@type": "DataDownload",
      "encodingFormat": "application/jsonl",
      "contentUrl": "https://axiomlocus.io/api/exports/training-data?dataset=scores&metro=sf&format=jsonl"
    }
  ],
  "variableMeasured": [
    { "name": "composite", "description": "Overall score 0-100" },
    { "name": "businessVitality", "description": "Business vitality signal 0-100" }
  ]
}
```

| Field              | Type   | Description                              |
| ------------------ | ------ | ---------------------------------------- |
| `@type`            | string | Always 'Dataset' (schema.org).           |
| `distribution`     | array  | Available download formats and URLs.     |
| `variableMeasured` | array  | Feature descriptions for ML consumption. |

## `GET` `/api/exports/training-data` [#get-apiexportstraining-data]


  Requires Bearer token.


Download training data in JSONL or CSV format for ML pipelines. Each row is one H3 cell with all features.

**Query parameters**

| Name      | Type   | Required | Default | Description                                               |
| --------- | ------ | -------- | ------- | --------------------------------------------------------- |
| `dataset` | string | ✓        |         | Dataset name: scores, permits, pois, crime, demographics. |
| `format`  | string |          | `jsonl` | Output format: jsonl or csv.                              |
| `metro`   | string |          |         | Metro slug filter.                                        |
| `limit`   | int    |          | `10000` | Max rows (50,000 max for Team plan).                      |
| `since`   | string |          |         | Only records updated since this ISO date.                 |

**Example**

```bash
curl "https://axiomlocus.io/api/exports/training-data?dataset=scores&format=jsonl&metro=sf&limit=1000" \
  -H "Authorization: Bearer al_your_key_here" -o training.jsonl
```

**Response**

```json
{"h3_index":"882a100d63fffff","metro":"sf","composite":76.2,"businessVitality":82,"populationMomentum":71,"demographics":80,"economicStrength":74,"developmentPipeline":78,"accessibility":69,"safety":65,"amenity":72}
{"h3_index":"882a100d65fffff","metro":"sf","composite":71.8,"businessVitality":75,"populationMomentum":68,"demographics":77,"economicStrength":70,"developmentPipeline":72,"accessibility":65,"safety":62,"amenity":69}
```

| Field            | Type   | Description                               |
| ---------------- | ------ | ----------------------------------------- |
| `h3_index`       | string | H3 cell identifier at resolution 8.       |
| `composite`      | float  | Overall composite score.                  |
| `[signal_group]` | float  | Individual signal group scores (8 total). |


# Monitoring (/locus/api/monitoring)



## `GET` `/api/monitors` [#get-apimonitors]


  Requires Bearer token.


List your monitored locations.

**Example**

```bash
curl "https://axiomlocus.io/api/monitors" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response**

```json
{
  "monitors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Mission District HQ",
      "lat": 37.7599,
      "lng": -122.4148,
      "created_at": "2025-12-01T08:00:00Z"
    }
  ]
}
```

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| `monitors`        | array  | Array of monitored location objects. |
| `monitors[].id`   | uuid   | Unique monitor identifier.           |
| `monitors[].name` | string | User-provided location name.         |
| `monitors[].lat`  | float  | Latitude.                            |
| `monitors[].lng`  | float  | Longitude.                           |

## `POST` `/api/monitors` [#post-apimonitors]


  Requires Bearer token.


Add a new monitored location.

**Request body**

```json
{
  "name": "Mission District HQ",
  "lat": 37.7599,
  "lng": -122.4148
}
```

| Field  | Type   | Required | Default | Description                         |
| ------ | ------ | -------- | ------- | ----------------------------------- |
| `name` | string | ✓        |         | A name for this monitored location. |
| `lat`  | float  | ✓        |         | Latitude.                           |
| `lng`  | float  | ✓        |         | Longitude.                          |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/monitors" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"Mission District HQ","lat":37.7599,"lng":-122.4148}'
```

**Response**

```json
{
  "monitor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Mission District HQ",
    "lat": 37.7599,
    "lng": -122.4148,
    "user_id": "...",
    "created_at": "2025-12-01T08:00:00Z"
  }
}
```

| Field     | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `monitor` | object | The newly created monitor object. |

## `DELETE` `/api/monitors` [#delete-apimonitors]


  Requires Bearer token.


Remove a monitored location.

**Query parameters**

| Name | Type | Required | Default | Description               |
| ---- | ---- | -------- | ------- | ------------------------- |
| `id` | uuid | ✓        |         | The monitor ID to delete. |

**Example**

```bash
curl -X DELETE "https://axiomlocus.io/api/monitors?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response**

```json
{
  "success": true
}
```

| Field     | Type    | Description                     |
| --------- | ------- | ------------------------------- |
| `success` | boolean | Whether the deletion succeeded. |

## `GET` `/api/alerts/history` [#get-apialertshistory]


  Requires Bearer token.


View alert history for your monitored locations.

**Example**

```bash
curl "https://axiomlocus.io/api/alerts/history" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response**

```json
{
  "alerts": [
    {
      "id": "a1b2c3d4",
      "monitor_id": "550e8400-...",
      "type": "score_change",
      "message": "Composite score dropped from 78 to 65",
      "created_at": "2025-12-15T14:30:00Z"
    }
  ]
}
```

| Field              | Type   | Description                                       |
| ------------------ | ------ | ------------------------------------------------- |
| `alerts`           | array  | Array of alert history objects.                   |
| `alerts[].type`    | string | Alert type (score\_change, source\_change, etc.). |
| `alerts[].message` | string | Human-readable alert description.                 |


# API overview (/locus/api/overview)



The Axiom Locus API exposes 35+ endpoints for location intelligence — composite scoring, POIs, permits, traffic, jobs, predictions, ML exports, monitoring, and PDF report generation.

## Base URL [#base-url]

```text
https://axiomlocus.io
```

The API currently uses two route conventions. The established endpoint families are
mounted directly under `/api/...` (for example `/api/score`, `/api/pois`,
`/api/export`, `/api/portfolios`, and `/api/webhooks/stripe`). A smaller set of
newer public integrations is versioned under `/api/v1/...`, including
`/api/v1/enrich`, `/api/v1/billing/entitlements`, `/api/v1/keys`,
`/api/v1/simulate/zoning`, `/api/v1/spatial-diagnostics`, and
`/api/v1/webhooks`. Use the path shown on each endpoint page; there is no single
version prefix applied to every route.

## Authentication [#authentication]

The free tier `GET /api/score` and `GET /api/pois` work without auth. Authentication for protected endpoints is endpoint-specific: many API endpoints use a Bearer API key, while `/api/export` requires an authenticated session. Follow the authentication requirement on each endpoint page.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://axiomlocus.io/api/bulk-score \
  -H "Content-Type: application/json" \
  -d '{"locations":[{"lat":37.77,"lng":-122.41}]}'
```

Generate tokens in **Settings → API Keys** in the Locus dashboard.

## Plans and access tiers [#plans-and-access-tiers]

Locus is sold as part of the cross-product Axiom Platform. The plan you're on determines daily API call limits, which endpoint families are unlocked, and how many API keys and team members you can provision. See the [full pricing page](https://axiomlocus.io/pricing) for the latest list, including features that overlap with Overwatch (maritime) and Codex (data normalization).

| Plan         | Price         | API calls / day | API keys  | Team members |
| ------------ | ------------- | --------------- | --------- | ------------ |
| Explorer     | Free          | 50              | 1         | 1            |
| Analyst      | $49/mo        | 500             | 1         | 1            |
| Professional | $199/mo       | 5,000           | 1         | 1            |
| Team         | $599/mo       | 25,000          | Multiple  | Unlimited    |
| Enterprise   | Contact sales | 100,000         | Unlimited | Unlimited    |

All paid plans include a 14-day free trial. Explorer requires no credit card.

### What unlocks at each tier [#what-unlocks-at-each-tier]

The free Explorer tier covers the unauthenticated reads (`GET /api/score`, `GET /api/pois`) and the Explorer map across all 22 metros — enough to evaluate a single location end-to-end. Paid tiers gate more advanced endpoints and exports:

* **Analyst** — 8 signal-group breakdowns on `/api/score`, [`GET /api/neighborhood-score`](/locus/api/location-data#get-apineighborhood-score), compare mode, heatmap overlays, and the full top 25 of composite [rankings](/locus/mcp-server) (the free tier shows only the top 3 rows of composite-tier lists).
* **Professional** — full 43-source enrichment, [webhooks](/locus/api/webhooks), score history and trends, congestion forecasting, sanctions screening, and government bid monitoring.
* **Team** — bulk CSV/JSON exports, [scheduled exports](/locus/api/scheduled-exports), [ML exports](/locus/api/ml-exports) (Croissant format), the [MCP server](/locus/mcp-server) with 32+ tools, and trade-flow analytics. Team is the entry point for shared workspaces.
* **Enterprise** — custom integrations, white-label PDF [reports](/locus/api/reports), cross-domain dashboards spanning Locus and Overwatch, dedicated SLA, and named account management.

When you exceed your tier's daily call limit the API returns `429 Too Many Requests` with a `Retry-After` header set to the seconds remaining until the next UTC midnight reset. Bulk endpoints count each location in a `locations[]` array as one call against your limit.

### Choosing a tier [#choosing-a-tier]

Pick **Explorer** for ad-hoc lookups, demos, and prototyping a single integration. Move to **Analyst** as soon as you need signal-group breakdowns or are scoring more than \~50 locations a day. **Professional** is the right starting point for production use cases that depend on enrichment, webhooks, or score history. Choose **Team** when you need bulk exports, the MCP server, or more than one operator on the account. **Enterprise** is for custom data integrations and SLA-backed deployments.

```bash
# Inspect the rate-limit headers on any authenticated request
curl -i -H "Authorization: Bearer YOUR_TOKEN" \
  "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194"

# Response headers include:
#   X-RateLimit-Limit:     5000
#   X-RateLimit-Remaining: 4982
#   X-RateLimit-Reset:     1714435200
```

To upgrade, downgrade, or view current usage, open **Settings → Billing** in the Locus dashboard. Plan changes take effect immediately, and rate limits switch to the new tier on the next request.

## Scoring profiles [#scoring-profiles]

The composite score and many endpoints accept a `profile` parameter that adjusts signal weights for the use case:

| Profile        | Optimized for                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `general`      | Default. Balanced across all signal groups.                                                     |
| `qsr`          | Quick-service restaurants — emphasis on foot traffic, demographics, competitor density.         |
| `self_storage` | Self-storage facilities — emphasis on housing turnover, population density, road accessibility. |
| `retail`       | Retail spaces — emphasis on foot traffic, parking, complementary tenants.                       |
| `office`       | Office leasing — emphasis on transit, daytime population, business vitality.                    |
| `data_center`  | Data center siting — emphasis on broadband, power infrastructure, environmental risk.           |
| `industrial`   | Industrial and logistics — emphasis on road accessibility, workforce availability, zoning.      |

## Confidence [#confidence]

Every score includes a `confidence` field (0.0–1.0) representing the ratio of data sources that returned data for the location. Coverage varies by metro and by signal — rural areas often have lower confidence than urban ones.

## Composite vs sub-scores [#composite-vs-sub-scores]

Composite scores roll up 8 signal groups:

1. **Business Vitality** (`businessVitality`) — net openings, category diversity, rating trajectory, license velocity, pioneer business presence
2. **Population Momentum** (`populationMomentum`) — net migration, income migration, population growth, vacancy trend
3. **Demographics** (`demographics`) — median income, population density, daytime population ratio, education, median age
4. **Economic Strength** (`economicStrength`) — employment growth, average wages, GDP growth, banking activity, small business lending
5. **Development Pipeline** (`developmentPipeline`) — permit activity, construction detection, land cover change, opportunity zones, permit velocity, permit valuation tier, permit scope quality
6. **Accessibility** (`accessibility`) — transit access, walkability, traffic flow, broadband, EV infrastructure, cell coverage
7. **Safety & Environment** (`safetyEnvironment`) — crime rate, flood risk (FEMA FIRM zones), flood loss history (FEMA NFIP claims), environmental risk, air quality, complaint density
8. **Amenity Demand** (`amenityDemand`) — job market, event density, school quality, food access, demand intent, competitive gravity

Use `GET /api/score` for the composite. Use the per-signal endpoints (`/api/pois`, `/api/permits`, `/api/traffic`, `/api/jobs`) for raw data.

## Quick start [#quick-start]


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    # 1. Score a single location (no auth)
    curl "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194"

    # 2. Find nearby points of interest
    curl "https://axiomlocus.io/api/pois?lat=37.7749&lng=-122.4194&radius=0.5"

    # 3. Score many locations in a single bulk request (auth required)
    curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"locations":[{"lat":37.77,"lng":-122.41},{"lat":34.05,"lng":-118.24}]}' \
      https://axiomlocus.io/api/bulk-score
    ```
  

  
    ```python
    import requests

    # 1. Score a single location (no auth)
    score = requests.get(
        "https://axiomlocus.io/api/score",
        params={"lat": 37.7749, "lng": -122.4194},
    ).json()

    # 2. Find nearby points of interest
    pois = requests.get(
        "https://axiomlocus.io/api/pois",
        params={"lat": 37.7749, "lng": -122.4194, "radius": 0.5},
    ).json()

    # 3. Score many locations in a single bulk request (auth required)
    bulk = requests.post(
        "https://axiomlocus.io/api/bulk-score",
        headers={"Authorization": "Bearer YOUR_TOKEN"},
        json={"locations": [{"lat": 37.77, "lng": -122.41}, {"lat": 34.05, "lng": -118.24}]},
    ).json()
    ```
  

  
    ```js
    // 1. Score a single location (no auth)
    const score = await fetch(
      "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194"
    ).then((r) => r.json());

    // 2. Find nearby points of interest
    const pois = await fetch(
      "https://axiomlocus.io/api/pois?lat=37.7749&lng=-122.4194&radius=0.5"
    ).then((r) => r.json());

    // 3. Score many locations in a single bulk request (auth required)
    const bulk = await fetch("https://axiomlocus.io/api/bulk-score", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        locations: [{ lat: 37.77, lng: -122.41 }, { lat: 34.05, lng: -118.24 }],
      }),
    }).then((r) => r.json());
    ```
  


## Where to from here [#where-to-from-here]


  
    `/api/score`

     and bulk scoring
  

  
    POIs, permits, traffic, jobs
  

  
    Forward-looking territory forecasts
  

  
    Generate branded PDF reports
  



# Portfolios (/locus/api/portfolios)



Portfolios group H3 cell locations into named collections for ongoing monitoring and scoring. Each portfolio can hold up to 2,000 locations, apply a custom [scoring formula](/locus/api/formulas), and track weighted composite scores with 30-day movement trends.

Portfolios support three visibility levels — `private` (owner only), `team`, and `org` — so you can share scoring results across your workspace.

## `GET` `/api/v1/locus/portfolios` [#get-apiv1locusportfolios]


  Requires session authentication.


List all portfolios you have access to, including aggregate scoring metrics.

**Response**

```json
{
  "portfolios": [
    {
      "id": "p_abc123",
      "name": "West Coast QSR Sites",
      "description": "Quick-service restaurant expansion candidates",
      "asset_class": "qsr",
      "active_formula_id": "f_def456",
      "visibility": "team",
      "member_count": 42,
      "weighted_composite": 71.8,
      "formula": {
        "id": "f_def456",
        "name": "QSR v2",
        "asset_class": "qsr",
        "version": 2
      },
      "latest_refresh_run": {
        "status": "completed",
        "requested_at": "2026-04-19T10:00:00Z",
        "completed_at": "2026-04-19T10:02:34Z"
      },
      "metrics": {
        "weighted_composite_30d_start": 69.2,
        "weighted_composite_30d_end": 71.8,
        "weighted_delta_30d": 2.6,
        "coverage_pct": 95.2,
        "weighted_coverage_pct": 96.1,
        "severe_exposure_pct": 4.8,
        "elevated_exposure_pct": 14.3,
        "stable_exposure_pct": 80.9
      },
      "created_at": "2026-03-01T08:00:00Z",
      "updated_at": "2026-04-19T10:02:34Z"
    }
  ]
}
```

| Field                           | Type           | Description                                           |
| ------------------------------- | -------------- | ----------------------------------------------------- |
| `member_count`                  | int            | Number of locations in the portfolio.                 |
| `weighted_composite`            | float \| null  | Weight-adjusted composite score across all locations. |
| `formula`                       | object \| null | Active scoring formula applied to this portfolio.     |
| `metrics.weighted_delta_30d`    | float \| null  | 30-day score movement (positive = improving).         |
| `metrics.coverage_pct`          | float          | Percentage of locations with scoring data.            |
| `metrics.severe_exposure_pct`   | float          | Weighted percentage of locations scoring below 30.    |
| `metrics.elevated_exposure_pct` | float          | Weighted percentage of locations scoring 30–50.       |
| `metrics.stable_exposure_pct`   | float          | Weighted percentage of locations scoring 50+.         |

**Example**

```bash
curl https://axiomlocus.io/api/v1/locus/portfolios \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## `POST` `/api/v1/locus/portfolios` [#post-apiv1locusportfolios]


  Requires session authentication.


Create a new portfolio. If you provide an `asset_class`, Locus automatically assigns the matching system scoring formula.

**Parameters**

| Name          | Type   | Required | Description                                                                                                                 |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | ✓        | Portfolio name.                                                                                                             |
| `description` | string |          | Human-readable description.                                                                                                 |
| `asset_class` | string |          | Asset class (e.g. `qsr`, `retail`, `office`, `industrial`, `self_storage`, `data_center`). Auto-assigns the system formula. |
| `visibility`  | string |          | `private` (default), `team`, or `org`.                                                                                      |
| `org_id`      | string |          | Workspace org id. Required when visibility is `team` or `org`.                                                              |
| `team_id`     | string |          | Workspace team id. Optional, used with `team` visibility.                                                                   |

**Example**

```bash
curl -X POST https://axiomlocus.io/api/v1/locus/portfolios \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Midwest Industrial Sites",
    "asset_class": "industrial",
    "description": "Distribution center candidates in the Midwest corridor"
  }'
```

**Response**

```json
{
  "portfolio": {
    "id": "p_new789",
    "name": "Midwest Industrial Sites",
    "asset_class": "industrial",
    "active_formula_id": "f_sys_industrial_v1",
    "visibility": "private",
    "member_count": 0,
    "weighted_composite": null,
    "created_at": "2026-04-20T12:00:00Z"
  }
}
```

***

## Portfolio locations [#portfolio-locations]

Manage the H3 cell locations within a portfolio. Each location is identified by an `h3_index` and `profile` pair.

### `GET` `/api/v1/locus/portfolios/{portfolioId}/locations` [#get-apiv1locusportfoliosportfolioidlocations]


  Requires session authentication.


List all locations in a portfolio with their current scores. If the portfolio has an active formula, scores are computed using the formula weights rather than the default composite.

**Response**

```json
{
  "locations": [
    {
      "id": "loc_001",
      "h3_index": "882a100d63fffff",
      "profile": "qsr",
      "weight": 1.5,
      "asset_class": "qsr",
      "source": "manual",
      "address_input": "123 Market St, San Francisco, CA",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "composite": 78.4,
      "metro_slug": "sf",
      "neighborhood": "Financial District",
      "formula_id_used": "f_def456",
      "formula_name_used": "QSR v2",
      "formula_version_used": 2,
      "created_at": "2026-03-15T09:00:00Z"
    }
  ]
}
```

| Field       | Type          | Description                                                                            |
| ----------- | ------------- | -------------------------------------------------------------------------------------- |
| `weight`    | float         | Relative importance of this location in portfolio aggregations (default 1).            |
| `source`    | string        | How the location was added: `manual` or `import`.                                      |
| `composite` | float \| null | Score computed with the active formula, or the default composite if no formula is set. |

### `POST` `/api/v1/locus/portfolios/{portfolioId}/locations` [#post-apiv1locusportfoliosportfolioidlocations]


  Requires session authentication.


Add a location to the portfolio. If a location with the same `h3_index` and `profile` already exists, it is updated (upsert).

**Parameters**

| Name            | Type   | Required | Description                                            |
| --------------- | ------ | -------- | ------------------------------------------------------ |
| `h3_index`      | string | ✓        | H3 cell id at resolution 8.                            |
| `profile`       | string |          | Scoring profile (default `general`).                   |
| `weight`        | number |          | Relative weight for portfolio aggregation (default 1). |
| `asset_class`   | string |          | Asset class label for this location.                   |
| `address_input` | string |          | Original address for reference.                        |
| `latitude`      | number |          | Latitude for display.                                  |
| `longitude`     | number |          | Longitude for display.                                 |

**Example**

```bash
curl -X POST https://axiomlocus.io/api/v1/locus/portfolios/p_abc123/locations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "h3_index": "882a100d63fffff",
    "profile": "qsr",
    "weight": 1.5,
    "address_input": "123 Market St, San Francisco, CA",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'
```

### `PATCH` `/api/v1/locus/portfolios/{portfolioId}/locations` [#patch-apiv1locusportfoliosportfolioidlocations]


  Requires session authentication.


Update a location's weight or asset class.

**Parameters**

| Name          | Type   | Required | Description                          |
| ------------- | ------ | -------- | ------------------------------------ |
| `h3_index`    | string | ✓        | H3 cell id to update.                |
| `profile`     | string |          | Scoring profile (default `general`). |
| `weight`      | number |          | New weight value (must be positive). |
| `asset_class` | string |          | New asset class label.               |

### `DELETE` `/api/v1/locus/portfolios/{portfolioId}/locations` [#delete-apiv1locusportfoliosportfolioidlocations]


  Requires session authentication.


Remove a location from the portfolio.

**Query parameters**

| Name       | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `h3_index` | string | ✓        | H3 cell id to remove.                |
| `profile`  | string |          | Scoring profile (default `general`). |

**Example**

```bash
curl -X DELETE "https://axiomlocus.io/api/v1/locus/portfolios/p_abc123/locations?h3_index=882a100d63fffff&profile=qsr" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

## Bulk import [#bulk-import]

### `POST` `/api/v1/locus/portfolios/{portfolioId}/locations/import` [#post-apiv1locusportfoliosportfolioidlocationsimport]


  Requires session authentication.


Import multiple locations into a portfolio in a single request. Accepts a JSON array of location objects. Existing locations (matching `h3_index` + `profile`) are updated; new ones are created.

**Request body**

```json
{
  "locations": [
    { "h3_index": "882a100d63fffff", "profile": "retail", "weight": 2.0, "address_input": "123 Market St" },
    { "h3_index": "882a100d65fffff", "profile": "retail", "weight": 1.0, "address_input": "456 Oak Ave" }
  ]
}
```

***

## Scoring refresh [#scoring-refresh]

### `GET` `/api/v1/locus/portfolios/{portfolioId}/refresh` [#get-apiv1locusportfoliosportfolioidrefresh]


  Requires session authentication.


List recent scoring refresh runs for the portfolio.

**Query parameters**

| Name    | Type   | Required | Description                               |
| ------- | ------ | -------- | ----------------------------------------- |
| `limit` | number |          | Max runs to return (default 20, max 100). |

**Response**

```json
{
  "runs": [
    {
      "id": "run_001",
      "status": "completed",
      "requested_at": "2026-04-19T10:00:00Z",
      "started_at": "2026-04-19T10:00:05Z",
      "completed_at": "2026-04-19T10:02:34Z",
      "error_message": null
    }
  ]
}
```

### `POST` `/api/v1/locus/portfolios/{portfolioId}/refresh` [#post-apiv1locusportfoliosportfolioidrefresh]


  Requires session authentication.


Queue a scoring refresh. The refresh is processed asynchronously — scores for all locations in the portfolio are recomputed with the latest data and the active formula.

**Response** (HTTP 202)

```json
{
  "run": {
    "id": "run_002",
    "status": "queued",
    "requested_at": "2026-04-20T12:00:00Z"
  }
}
```

| Status      | Description                               |
| ----------- | ----------------------------------------- |
| `queued`    | Waiting for the next processing cycle.    |
| `running`   | Scoring is in progress.                   |
| `completed` | All locations have been rescored.         |
| `failed`    | An error occurred. Check `error_message`. |


# Predictions (/locus/api/predictions)



## `GET` `/api/lead-lag` [#get-apilead-lag]


  Requires Bearer token.


Survival curve analysis showing how one signal leads or lags another. Useful for predicting which neighborhoods will gentrify, decline, or see permit surges.

**Query parameters**

| Name         | Type   | Required | Default | Description                                                        |
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------ |
| `cause`      | string | ✓        |         | Leading signal group (e.g. businessVitality, populationMomentum).  |
| `effect`     | string | ✓        |         | Lagging signal group (e.g. developmentPipeline, economicStrength). |
| `metro`      | string |          |         | Metro slug filter. Omit for all metros.                            |
| `lag_months` | int    |          | `12`    | Maximum lag window in months (1-24).                               |

**Example**

```bash
curl "https://axiomlocus.io/api/lead-lag?cause=businessVitality&effect=developmentPipeline&metro=sf" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{
  "cause": "businessVitality",
  "effect": "developmentPipeline",
  "metro": "sf",
  "peak_lag_months": 6,
  "peak_correlation": 0.72,
  "survival_curve": [
    { "month": 0, "correlation": 0.12 },
    { "month": 3, "correlation": 0.45 },
    { "month": 6, "correlation": 0.72 },
    { "month": 9, "correlation": 0.58 },
    { "month": 12, "correlation": 0.31 }
  ],
  "interpretation": "Business vitality changes lead development pipeline activity by ~6 months in SF."
}
```

| Field              | Type   | Description                                          |
| ------------------ | ------ | ---------------------------------------------------- |
| `peak_lag_months`  | int    | Month offset where correlation is strongest.         |
| `peak_correlation` | float  | Pearson correlation at peak lag (0-1).               |
| `survival_curve`   | array  | Monthly correlation values over the lag window.      |
| `interpretation`   | string | Human-readable summary of the lead-lag relationship. |

## `GET` `/api/permits/predict` [#get-apipermitspredict]


  Requires Bearer token.


Sequence prediction for building permit activity at the H3 cell level. Uses historical permit patterns to forecast future issuance.

**Query parameters**

| Name       | Type   | Required | Default | Description                        |
| ---------- | ------ | -------- | ------- | ---------------------------------- |
| `h3_index` | string | ✓        |         | H3 hex index at resolution 8.      |
| `horizon`  | int    |          | `6`     | Forecast horizon in months (1-12). |

**Example**

```bash
curl "https://axiomlocus.io/api/permits/predict?h3_index=882a100d63fffff&horizon=6" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{
  "h3_index": "882a100d63fffff",
  "historical_avg_monthly": 4.2,
  "forecast": [
    { "month": "2026-04", "predicted_permits": 5, "confidence": 0.85 },
    { "month": "2026-05", "predicted_permits": 6, "confidence": 0.78 },
    { "month": "2026-06", "predicted_permits": 4, "confidence": 0.71 },
    { "month": "2026-07", "predicted_permits": 7, "confidence": 0.65 },
    { "month": "2026-08", "predicted_permits": 5, "confidence": 0.59 },
    { "month": "2026-09", "predicted_permits": 4, "confidence": 0.52 }
  ],
  "trend": "increasing",
  "model": "arima_h3_v2"
}
```

| Field                          | Type   | Description                                                 |
| ------------------------------ | ------ | ----------------------------------------------------------- |
| `historical_avg_monthly`       | float  | Average monthly permits over the last 12 months.            |
| `forecast`                     | array  | Monthly predictions with confidence intervals.              |
| `forecast[].predicted_permits` | int    | Predicted permit count for the month.                       |
| `forecast[].confidence`        | float  | Model confidence (0-1), decreases with horizon.             |
| `trend`                        | string | Overall trend direction: increasing, stable, or decreasing. |


# Reports (/locus/api/reports)



## `GET` `/api/report` [#get-apireport]


  Requires Bearer token.


Generate a branded PDF location report.

**Query parameters**

| Name      | Type   | Required | Default           | Description                        |
| --------- | ------ | -------- | ----------------- | ---------------------------------- |
| `lat`     | float  | ✓        |                   | Latitude.                          |
| `lng`     | float  | ✓        |                   | Longitude.                         |
| `name`    | string |          | `Location Report` | Report title / location name.      |
| `profile` | string |          | `general`         | Scoring profile.                   |
| `client`  | string |          | `Client`          | Client name for the report header. |

**Example**

```bash
curl "https://axiomlocus.io/api/report?lat=37.7749&lng=-122.4194&name=Mission+District" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o report.pdf
```

**Response**

```json
# Binary PDF response
Content-Type: application/pdf
Content-Disposition: attachment; filename="axiom-locus-report-mission-district.pdf"
```

## `GET` `/api/places-photo` [#get-apiplaces-photo]

Proxy for business photos. Supports both Places API (New) resource names and legacy photo references returned by `/api/location-data`.

**Query parameters**

| Name  | Type   | Required | Default | Description                                                                                                                                                                                                                                                        |
| ----- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ref` | string | ✓        |         | Photo reference string from POI data. Must match either a Places API (New) resource name (`places/{place_id}/photos/{photo_id}`) or a legacy photo reference (8–2048 characters, `A–Z`, `a–z`, `0–9`, `_`, or `-`). Other formats return `400 Invalid ref format`. |
| `w`   | int    |          | `100`   | Image width in pixels. Values are clamped to the range `1`–`1600`; non-numeric values fall back to the default.                                                                                                                                                    |

**Example**

```bash
curl "https://axiomlocus.io/api/places-photo?ref=Aap_uE...&w=200" -o photo.jpg
```

**Response**

```json
# Binary JPEG response
Content-Type: image/jpeg
```


# Scheduled exports (/locus/api/scheduled-exports)



Schedule recurring exports of cell scores from Locus and have them emailed to you on a weekly or monthly cadence. Each delivery runs the saved filter against the latest `cell_scores` and attaches the result as a CSV or JSON file.

For one-off downloads, use the on-demand exports endpoint described in [ML exports](/locus/api/ml-exports).

## When to use it [#when-to-use-it]

Use scheduled exports when you want a hands-off feed of Locus scores for a specific market, score band, or analyst inbox — for example:

* A weekly CSV of all cells in a metro for territory planning.
* A monthly JSON snapshot of high-composite cells (e.g. composite ≥ 70) for portfolio review.
* Recurring deliveries to a shared analyst alias so the same dataset lands in the same place every week.

Each schedule is owned by the user that creates it and can only be read, updated, or deleted by that user.

## Endpoints [#endpoints]

All endpoints require an authenticated session. Schedules are scoped to the calling user.

### `GET` `/api/scheduled-exports` [#get-apischeduled-exports]

List scheduled exports owned by the current user.

**Response**

```json
{
  "schedules": [
    {
      "id": "8c1f9f0a-3a9b-4c7e-9f4d-2b8c4d3e1a90",
      "name": "Weekly SF scores",
      "filters": { "metro": "sf", "compositeMin": 70 },
      "format": "csv",
      "frequency": "weekly",
      "target_email": "analyst@yourcompany.com",
      "last_sent_at": "2026-04-22T08:00:12Z",
      "last_error": null,
      "created_at": "2026-04-15T14:22:01Z"
    }
  ]
}
```

| Field          | Type           | Description                                                                         |
| -------------- | -------------- | ----------------------------------------------------------------------------------- |
| `id`           | string (UUID)  | Schedule identifier. Pass to `DELETE` to remove.                                    |
| `name`         | string         | Human-readable label, used in the email subject and attachment filename.            |
| `filters`      | object         | Filter blob applied to `cell_scores` on each run. See [Filters](#filters).          |
| `format`       | string         | `csv` or `json`.                                                                    |
| `frequency`    | string         | `weekly` or `monthly`.                                                              |
| `target_email` | string         | Address that receives each delivery.                                                |
| `last_sent_at` | string \| null | Timestamp of the last successful run. `null` if it has never run.                   |
| `last_error`   | string \| null | Error message from the most recent failed run, or `null` if the last run succeeded. |
| `created_at`   | string         | When the schedule was created.                                                      |

### `POST` `/api/scheduled-exports` [#post-apischeduled-exports]

Create a new scheduled export.

**Body parameters**

| Name           | Type   | Required | Description                                                                               |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `name`         | string | ✓        | Schedule name (≤120 characters).                                                          |
| `target_email` | string | ✓        | Address to deliver the export to. Must contain `@`.                                       |
| `format`       | string |          | `csv` (default) or `json`.                                                                |
| `frequency`    | string |          | `weekly` (default) or `monthly`.                                                          |
| `filters`      | object |          | Filter blob applied to `cell_scores`. Defaults to `{}` (all cells). Maximum 8 KB of JSON. |

#### Filters [#filters]

The filter blob is stored as JSON and re-evaluated on every run, so updates to `cell_scores` show up automatically. The cron worker currently honors:

| Key            | Type   | Description                                     |
| -------------- | ------ | ----------------------------------------------- |
| `metro`        | string | Metro slug (e.g. `sf`, `nyc`).                  |
| `compositeMin` | number | Lower bound on the composite score (inclusive). |
| `compositeMax` | number | Upper bound on the composite score (inclusive). |

Each delivery is capped at 5,000 rows, ordered by descending composite. If the filter matches no rows, the run is recorded as successful and no email is sent.

**Example — create a weekly schedule**

```bash
curl -X POST https://axiomlocus.io/api/scheduled-exports \
  -H "Content-Type: application/json" \
  --cookie "sb-access-token=..." \
  -d '{
    "name": "Weekly SF scores",
    "target_email": "analyst@yourcompany.com",
    "format": "csv",
    "frequency": "weekly",
    "filters": { "metro": "sf", "compositeMin": 70 }
  }'
```

**Response**

```json
{
  "schedule": {
    "id": "8c1f9f0a-3a9b-4c7e-9f4d-2b8c4d3e1a90",
    "name": "Weekly SF scores",
    "filters": { "metro": "sf", "compositeMin": 70 },
    "format": "csv",
    "frequency": "weekly",
    "target_email": "analyst@yourcompany.com",
    "created_at": "2026-04-29T19:00:00Z"
  }
}
```

### `DELETE` `/api/scheduled-exports?id=` [#delete-apischeduled-exportsiduuid]

Delete a scheduled export. The `id` must be a UUID owned by the current user.

```bash
curl -X DELETE \
  "https://axiomlocus.io/api/scheduled-exports?id=8c1f9f0a-3a9b-4c7e-9f4d-2b8c4d3e1a90" \
  --cookie "sb-access-token=..."
```

**Response**

```json
{ "success": true }
```

## Delivery cadence [#delivery-cadence]

A cron worker evaluates schedules every Monday at 08:00 UTC and runs any schedule whose `last_sent_at` is older than its cadence (or has never run):

* `weekly` — runs once `last_sent_at` is at least 7 days old.
* `monthly` — runs once `last_sent_at` is at least 30 days old.

Because the worker fires weekly, weekly is the floor cadence — monthly schedules will fire on the first Monday after their 30-day window elapses.

## Email format [#email-format]

Each successful run sends an email from `Axiom Locus ` with:

* **Subject:** `Your scheduled Axiom Locus export:  ( rows)`
* **Attachment:** `-.`

CSV attachments include a header row and the columns `h3_index`, `metro_slug`, `neighborhood`, `lat`, `lng`, `composite`, `confidence`, the eight signal-group scores (`business_vitality`, `population_momentum`, `demographics`, `economic_strength`, `development_pipeline`, `accessibility`, `safety_environment`, `amenity_demand`), and `computed_at`. JSON attachments contain an array of objects with the same keys.

## Failure handling [#failure-handling]

If a run fails (for example, an upstream Resend outage), the error message is written to `last_error` on the schedule and the schedule remains due — the worker will retry on the next cron tick. A successful run clears `last_error` and bumps `last_sent_at`. List the schedule with `GET` to see whether the last run succeeded.

## Limits [#limits]

| Limit                | Value                |
| -------------------- | -------------------- |
| Filter blob size     | 8 KB of JSON         |
| Schedule name length | 120 characters       |
| Rows per delivery    | 5,000                |
| Cron cadence         | Mondays at 08:00 UTC |


  S3 delivery is not yet supported — schedules deliver to email only.



# Webhooks (/locus/api/webhooks)



## `POST` `/api/v1/webhooks` [#post-apiv1webhooks]


  Requires Bearer token.


Register a webhook to receive real-time notifications when scores change, new permits are filed, or monitored locations trigger alerts.

**Request body**

```json
{
  "url": "https://your-app.com/hooks/axiom",
  "events": ["score.changed", "permit.filed", "alert.triggered"],
  "secret": "whsec_your_signing_secret"
}
```

| Field    | Type   | Required | Default | Description                                                                                                                        |
| -------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `url`    | string | ✓        |         | HTTPS endpoint to receive webhook POST requests.                                                                                   |
| `events` | array  | ✓        |         | Events to subscribe to: score.changed, permit.filed, alert.triggered, monitor.report.                                              |
| `secret` | string |          |         | Signing secret for HMAC-SHA256 payload verification. Stored encrypted at rest and decrypted only when signing outbound deliveries. |

**Example**

```bash
curl -X POST "https://axiomlocus.io/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer al_your_key_here" \
  -d '{"url":"https://your-app.com/hooks/axiom","events":["score.changed","permit.filed"]}'
```

**Response**

```json
{
  "webhook": {
    "id": "wh_abc123def456",
    "url": "https://your-app.com/hooks/axiom",
    "events": ["score.changed", "permit.filed"],
    "active": true,
    "created_at": "2026-03-31T12:00:00Z"
  }
}
```

| Field            | Type    | Description                                |
| ---------------- | ------- | ------------------------------------------ |
| `webhook.id`     | string  | Unique webhook identifier (prefixed wh\_). |
| `webhook.events` | array   | Subscribed event types.                    |
| `webhook.active` | boolean | Whether the webhook is currently active.   |

## `GET` `/api/v1/webhooks` [#get-apiv1webhooks]


  Requires Bearer token.


List all registered webhooks for your account.

**Example**

```bash
curl "https://axiomlocus.io/api/v1/webhooks" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{
  "webhooks": [
    {
      "id": "wh_abc123def456",
      "url": "https://your-app.com/hooks/axiom",
      "events": ["score.changed", "permit.filed"],
      "active": true,
      "created_at": "2026-03-31T12:00:00Z",
      "last_delivery": "2026-03-31T14:22:00Z",
      "delivery_success_rate": 0.98
    }
  ]
}
```

| Field                              | Type   | Description                              |
| ---------------------------------- | ------ | ---------------------------------------- |
| `webhooks`                         | array  | All registered webhook objects.          |
| `webhooks[].delivery_success_rate` | float  | Success rate of recent deliveries (0-1). |
| `webhooks[].last_delivery`         | string | Timestamp of last delivery attempt.      |

## `DELETE` `/api/v1/webhooks` [#delete-apiv1webhooks]


  Requires Bearer token.


Delete a webhook registration.

**Query parameters**

| Name | Type   | Required | Default | Description                 |
| ---- | ------ | -------- | ------- | --------------------------- |
| `id` | string | ✓        |         | Webhook ID (prefixed wh\_). |

**Example**

```bash
curl -X DELETE "https://axiomlocus.io/api/v1/webhooks?id=wh_abc123def456" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json
{ "success": true }
```

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `success` | boolean | Whether the webhook was successfully deleted. |


# Admin authentication (/overwatch/api/admin-auth)



Admin authorization is the separate operator gate for sensitive Axiom Overwatch
API operations. It is not an API-key tier and it is not cron authentication. An
authorized request can be made by a signed-in Supabase user whose identity or
trusted role is configured for admin access, or by a configured machine key.


  Admin authorization is implemented by the shared `requireAuth` helper. The
  endpoints in [Admin-gated API operations](#admin-gated-api-operations) call that
  helper directly; it does not look up or authorize database API-key tiers.


## Authorization evaluation order [#authorization-evaluation-order]

`requireAuth` evaluates an admin request in this order:

1. It applies the admin-attempt rate limit: more than 10 attempts per minute
   from the same source IP receive `429`.
2. It checks that at least one of the four `ADMIN_*` authorization paths below
   is configured. If none is configured, it returns `403`.
3. It reads the current Supabase session user and checks the user's ID against
   `ADMIN_USER_IDS`.
4. It checks the user's trusted `app_metadata` roles against
   `ADMIN_ROLE_CLAIMS`.
5. It checks the supplied machine key against `ADMIN_MACHINE_KEYS`.
6. It checks the same machine key against the legacy `ADMIN_API_KEY` fallback.

The first matching path authorizes the request. A nonmatching request returns
`401`; the protected route does not continue into its handler.

For a machine actor, the helper reads `X-API-Key` first. If that header is
absent, it reads `Authorization: Bearer `. Supplying both headers uses the
`X-API-Key` value.

### Human actors [#human-actors]

Human authorization starts with the authenticated Supabase user for the
request. `ADMIN_USER_IDS` matches the user's immutable ID. Role authorization
reads only `app_metadata`, not `user_metadata`: the latter must not grant admin
access because it is commonly user-writable. The accepted role fields are
`role`, `roles`, `admin_role`, `admin_roles`, `app_role`, and `app_roles`; each
may be a string or an array of strings.

### Machine actors [#machine-actors]

Machine automation can send either supported key header. Machine-key comparison
uses a digest and constant-time equality check. `ADMIN_MACHINE_KEYS` is checked
before the legacy key, so an automation key present in both configurations is
resolved as a machine-key authorization rather than a legacy authorization.


  There is no route-specific scope grammar in the current implementation. Every
  matching value in `ADMIN_MACHINE_KEYS` authorizes every operation in the table
  below. A value such as `scope:imports` is only a literal key value unless it
  exactly matches the configured secret; it does not limit access to imports.


## Environment variables [#environment-variables]

The four admin settings are comma-separated lists where noted. Empty list items
are ignored and surrounding whitespace is removed. The examples below are
deliberately fake placeholders, not usable credentials.

| Variable             | Format and fake example                                                                                              | Authorization semantics                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ADMIN_USER_IDS`     | Comma-separated Supabase user IDs. Example: `user-placeholder-001,user-placeholder-002`                              | User ID entries are lowercased after trimming and compared to the signed-in user's ID. A match is the first authorization path.                                          |
| `ADMIN_ROLE_CLAIMS`  | Comma-separated role names. Example: `ops,admin`                                                                     | Entries and candidate role strings are lowercased. A match must be in the signed-in user's `app_metadata`; user metadata is ignored.                                     |
| `ADMIN_MACHINE_KEYS` | Comma-separated machine-key values. Example: `example-machine-key-a-not-a-secret,example-machine-key-b-not-a-secret` | Entries are trimmed but remain case-sensitive. Any matching entry authorizes all admin-gated operations; the value can arrive in `X-API-Key` or `Authorization: Bearer`. |
| `ADMIN_API_KEY`      | One legacy machine-key value. Example: `legacy-example-not-a-secret`                                                 | A nonempty exact match is considered only after the three preferred paths. It remains supported for compatibility, but is the broad legacy fallback.                     |

`CRON_SECRET` is deliberately separate. Cron routes use it only through
`isAuthorizedCronRequest`, which accepts `Authorization: Bearer `;
it does not authorize the admin-gated operations on this page.

## Machine-key requests [#machine-key-requests]

Use one of the supported headers. The following command uses a fake placeholder
and the audit-log operation as an example.


  
    ```bash X-API-Key
    curl -X GET \
      -H "X-API-Key: example-machine-key-not-a-secret" \
      https://www.axiomoverwatch.io/api/v1/admin/audit-log
    ```
  

  
    ```bash Authorization
    curl -X GET \
      -H "Authorization: Bearer example-machine-key-not-a-secret" \
      https://www.axiomoverwatch.io/api/v1/admin/audit-log
    ```
  



  `ADMIN_MACHINE_KEYS` accepts more than one comma-separated value. This lets an
  operator configure a replacement machine key before removing an old one, but
  each configured value has the same full admin access described above.


## Admin-gated API operations [#admin-gated-api-operations]

These are the current direct call sites of `requireAuth`. Methods not listed
here may have their own API-key, session, analyst, or public-access rules, but
they are not protected by this admin helper.

### Operations and configuration [#operations-and-configuration]

| Method | Path                          | Admin operation                                                                             |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------- |
| `GET`  | `/api/v1/admin/audit-log`     | Read audit records, with filters and optional CSV output.                                   |
| `POST` | `/api/v1/calibration`         | Create or replace a manual vessel-type calibration.                                         |
| `POST` | `/api/v1/congestion/refresh`  | Request a manual congestion-index refresh.                                                  |
| `POST` | `/api/v1/freight-rates`       | Create or update a freight-rate record.                                                     |
| `GET`  | `/api/v1/keys`                | List API-key metadata; key hashes are not returned.                                         |
| `POST` | `/api/v1/keys`                | Create a `free`, `starter`, or `pro` API key. This route does not create `admin`-tier keys. |
| `POST` | `/api/v1/pi-coverage/import`  | Bulk-import P\&I coverage from a plain-text CSV body.                                       |
| `GET`  | `/api/v1/webhooks`            | List configured webhooks without their secrets.                                             |
| `POST` | `/api/v1/webhooks`            | Create a webhook.                                                                           |
| `POST` | `/api/v1/webhooks/slack-test` | Send a test request to a Slack webhook URL.                                                 |

## Dashboard admin surfaces [#dashboard-admin-surfaces]

The `/dashboard` layout requires a signed-in Supabase user. Within that
authenticated dashboard, the current code has two dedicated admin surfaces:

* `/dashboard/admin/audit-log` accepts a key in its client form and sends it as
  `X-API-Key` to `GET /api/v1/admin/audit-log`.
* `/dashboard/admin/pi-import` accepts a key in its client form and sends it as
  `X-API-Key` to `POST /api/v1/pi-coverage/import`.

Those page components do not add a separate user-ID or role check before they
render. The admin decision happens when the protected API operation calls
`requireAuth`. The P\&I page also loads `/api/v1/pi-clubs` without a key; that
directory request is session-authenticated for a signed-in dashboard user and
is not one of the admin-gated operations listed above.

## Failure behavior [#failure-behavior]

Admin authorization is fail-closed. The helper returns an error response before
the route handler performs its sensitive work.

| Status | Response body                                | When it occurs                                                                                               |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `429`  | `{ "error": "Too many auth attempts" }`      | More than 10 attempts in one minute from the same source IP.                                                 |
| `403`  | `{ "error": "Admin access not configured" }` | None of `ADMIN_USER_IDS`, `ADMIN_ROLE_CLAIMS`, `ADMIN_MACHINE_KEYS`, or `ADMIN_API_KEY` is configured.       |
| `401`  | `{ "error": "Unauthorized" }`                | A configured admin path exists, but the session user and supplied machine key do not match any allowed path. |

For example, a machine request with an unconfigured key receives:

**Response**

```json
{ "error": "Unauthorized" }
```

The individual operation can return additional validation or service errors
after authorization succeeds. Those responses are specific to the endpoint and
do not mean that admin authorization was granted to an unauthenticated caller.

## Moving off `ADMIN_API_KEY` [#moving-off-admin_api_key]

`ADMIN_API_KEY` remains in the code as a compatibility fallback, but the
preferred configuration is an immutable user ID or trusted app-metadata role
for people and `ADMIN_MACHINE_KEYS` for automation.


  
    ### Configure the preferred paths [#configure-the-preferred-paths]

    Add the required human identities to `ADMIN_USER_IDS` and/or trusted role names
    to `ADMIN_ROLE_CLAIMS`. Add each automation credential to
    `ADMIN_MACHINE_KEYS`.
  

  
    ### Update machine callers [#update-machine-callers]

    Send the new configured machine value through `X-API-Key` or
    `Authorization: Bearer`. When both `ADMIN_MACHINE_KEYS` and `ADMIN_API_KEY` are
    present, the machine-key check is evaluated first.
  

  
    ### Remove the legacy fallback [#remove-the-legacy-fallback]

    After callers no longer depend on the legacy value, remove `ADMIN_API_KEY`.
    At least one remaining admin path must be configured or all protected routes
    will return `403`.
  



# Admin & Billing (/overwatch/api/admin)



API key management, billing, and subscription plans.


  Admin endpoints require 

  [admin authorization](/overwatch/api/admin-auth)

  . Billing and public endpoints retain their own access rules.


## `GET` `/api/v1/keys` [#get-apiv1keys]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


List your API keys.

**Response**

```json
{ "keys": [] }
```

Each `keys` entry carries `id`, `name`, `email`, `tier`, `rate_limit`, `enabled`, `created_at`, `last_used_at` — the key hash itself is never returned.

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/keys
```

## `POST` `/api/v1/keys` [#post-apiv1keys]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Create a new API key.

**Parameters** (JSON body)

| Name      | Type   | Required | Description                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `name`    | string | Yes      | Key owner/label                                                                              |
| `email`   | string | Yes      | Key owner's email                                                                            |
| `user_id` | string | Yes      | Owning user ID                                                                               |
| `tier`    | string |          | Default `free`. One of `free`, `starter`, `pro` — this route cannot create `admin`-tier keys |

**Response**

```json
{
  "api_key": {},
  "warning": "Save this key now. It cannot be retrieved again."
}
```

The `api_key` object carries `id`, `name`, `email`, `tier`, `rate_limit`, `created_at`, and the raw `key` (returned only this once).

**Error responses**

| Status | When                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | Invalid JSON body; missing `name`, `email`, or `user_id`; or `tier` is not `free`/`starter`/`pro` |
| `500`  | Insert failed                                                                                     |

See [admin authorization](/overwatch/api/admin-auth) for the `401`/`403`/`429` failure modes shared by all admin-gated endpoints.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/keys \
  -d '{"key":"value"}'
```

## `GET` `/api/v1/billing/plans` [#get-apiv1billingplans]

List available subscription plans with pricing and features.

**Response**

```json
{ "plans": [] }
```

Each `plans` entry carries `tier`, `price`, `currency`, `requests_per_month`, `features`, and (for the flagship bundle only) `flagship`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/billing/plans
```

## `GET` `/api/v1/billing/entitlements` [#get-apiv1billingentitlements]


  No API key or admin authorization required. Reads the caller's Supabase session cookie, if any, and falls back to free-tier defaults with 

  `isAuthenticated: false`

   when there is no session.


Resolve current user entitlements across Overwatch and Locus products.

**Response**

```json
{
  "entitlements": {
    "isAuthenticated": false,
    "plan": "free",
    "product": "overwatch",
    "hasBundle": false,
    "canAccessOverwatch": false,
    "canAccessLocus": false
  }
}
```

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/billing/entitlements
```

## `POST` `/api/v1/billing/checkout` [#post-apiv1billingcheckout]


  Requires a signed-in Supabase session (browser cookie) — not an API key. Returns 

  `401`

   if there is no session.


Create a Stripe checkout session for a subscription plan.

**Parameters** (JSON body)

| Name   | Type   | Required | Description                                                                                                           |
| ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `plan` | string |          | Default `starter`. One of `starter`, `pro`, `professional`, `supply_chain_risk` — must have a configured Stripe price |

**Response**

```json
{ "url": "" }
```

**Error responses**

| Status | When                                                        |
| ------ | ----------------------------------------------------------- |
| `400`  | Invalid JSON body, or `plan` has no configured Stripe price |
| `401`  | No authenticated session                                    |
| `500`  | Stripe API error                                            |
| `503`  | Billing not configured (`STRIPE_SECRET_KEY` unset)          |

**Example**

```bash
curl -X POST \
  --cookie "" \
  https://www.axiomoverwatch.io/api/v1/billing/checkout \
  -d '{"plan":"starter"}'
```


# Alerts (/overwatch/api/alerts)



Platform alerts for sanctions matches, river level warnings, dark fleet events, and more. The alert system includes a unified cross-product inbox, a rule engine for custom filtering, multi-channel notifications, and a delivery audit trail.

## `GET` `/api/v1/alerts` [#get-apiv1alerts]


  Requires API key. Currently returns 

  `503`

   for every external API-key caller — see 

  **Errors**

  .


Get active platform alerts. Filter by severity or type.

**Parameters**

| Name             | Type   | Required | Description                                    |
| ---------------- | ------ | -------- | ---------------------------------------------- |
| `severity`       | string |          | `critical`, `warning`, or `info`               |
| `type`           | string |          | `sanctions_match`, `river_level`, `dark_fleet` |
| `unacknowledged` | string |          | `true` to only show unread alerts              |
| `cursor`         | string |          | ISO timestamp for cursor pagination            |
| `limit`          | number |          | Default 20, capped by your access tier         |

**Response**

```json
{
  "alerts": [],
  "count": 12,
  "unacknowledged": 3,
  "tier": "pro",
  "pagination": { "limit": 20, "has_more": true, "next_cursor": "2026-04-17T08:00:00Z" }
}
```

Each `alerts` entry returns the full `platform_alerts` row (the handler selects `*`).

**Errors**

* `503` — `Personal alert feeds are not launch-supported` — returned whenever the request resolves to a user id. Every external API-key call currently hits this branch; only calls with no resolved user (e.g. the internal dashboard) get alert data back.
* `500` — Internal server error (Supabase query failure)

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/alerts?severity=critical
```

## `GET` `/api/v1/alerts/unified` [#get-apiv1alertsunified]


  Requires a signed-in dashboard session (Supabase auth cookie) — not an API key.


Unified cross-product inbox combining maritime and Locus alerts in a single chronological feed. Aggregates dark events, spoofing detections, motif alerts, monitoring alerts, and disruption signals. Per-user read/resolved/snoozed state is persisted server-side and overlaid onto each alert.

**Parameters**

| Name        | Type   | Required | Description                                                                                                      |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `product`   | string |          | `all` (default), `overwatch`, or `locus` — `locus` currently returns no alerts (no Locus source is wired in yet) |
| `source`    | string |          | `all` (default), `dark`, `spoofing`, `motif`, `monitoring`, or `disruption`                                      |
| `severity`  | string |          | `critical`, `warning`, or `info`                                                                                 |
| `watchlist` | string |          | `true` to only include watched vessels                                                                           |
| `portfolio` | string |          | Locus portfolio id filter                                                                                        |
| `state`     | string |          | `all` (default), `open`, `read`, `resolved`, `snoozed` — applied server-side against persisted per-user state    |
| `cursor`    | string |          | Opaque pagination cursor from a prior response's `next_cursor`                                                   |
| `limit`     | number |          | Default 25, max 100                                                                                              |

**Response**

```json
{
  "alerts": [
    {
      "id": "dark:456",
      "source": "dark",
      "source_alert_id": "456",
      "product": "overwatch",
      "severity": "critical",
      "title": "Dark event detected: IMO 9622629",
      "detail": "AIS gap 18.0h | tier high | risk 82",
      "description": "AIS gap 18.0h | tier high | risk 82",
      "occurred_at": "2026-04-18T03:22:00Z",
      "href": "/dashboard/risk/events",
      "metadata": { "imo_number": "9622629", "gap_duration_hours": 18 },
      "state": "open"
    }
  ],
  "count": 1,
  "pagination": { "limit": 25, "has_more": false, "next_cursor": null },
  "filters": { "product": "all", "source": "all", "severity": null, "watchlist": false, "portfolio": null, "state": "all", "state_filter_applied": true }
}
```

Every `alerts` entry carries `id`, `source`, `source_alert_id`, `product`, `severity`, `title`, `detail`, `description`, `occurred_at`, `href`, `metadata`, `state`; `metadata` contents vary by source (e.g. `dark` carries `imo_number`, `gap_duration_hours`, `risk_score`, `risk_tier`, `detection_source`, `subtype`).

**Errors**

* `401` — Unauthorized (no signed-in session)
* `503` — `Alert state is temporarily unavailable` — returned when persisted alert state cannot be read; response body includes `degraded: true`

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/alerts/unified?product=overwatch&state=open
```

## `POST` `/api/v1/alerts/unified/state` [#post-apiv1alertsunifiedstate]


  Requires a signed-in dashboard session (Supabase auth cookie) — not an API key.


Set per-user state for a unified alert—mark it as read, resolved, snoozed, or reopen it. State is persisted server-side with compare-and-set semantics: concurrent mutations from multiple browser tabs are ordered by `client_updated_at`, and the newest intent wins.


  Only alerts within the 14-day lookback window are eligible for state mutations. The server verifies alert visibility against the authenticated, RLS-bound source table before applying any state change.


**Parameters**

| Name           | Type   | Required | Description                                                                                                                                                                                                    |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alert_id`     | string | ✓        | Alert id in `source:id` format (e.g. `dark:456`). Source must be one of `dark`, `spoofing`, `motif`, `monitoring`, or `disruption`; id must be an integer for `dark`/`disruption` or a UUID for other sources. |
| `action`       | string | ✓        | `read`, `resolve`, `snooze`, or `open`                                                                                                                                                                         |
| `snooze_until` | string |          | Future ISO timestamp; defaults to +24 hours for snooze                                                                                                                                                         |
| `intent`       | object | ✓        | Compare-and-set intent with `client_updated_at` (ISO timestamp within ±5 minutes of server time) and `mutation_id` (UUID v4). The newest `client_updated_at` wins concurrent mutations.                        |

**Response**

```json
{
  "ok": true,
  "persisted": true,
  "applied": true,
  "alert_id": "dark:456",
  "action": "resolve",
  "source": "dark",
  "source_alert_id": "456",
  "state": { "read_at": "2026-04-18T10:00:00Z", "resolved_at": "2026-04-18T10:00:00Z", "snoozed_until": null }
}
```

The `applied` field is `true` when the mutation was applied, and `false` when a concurrent mutation with a newer `client_updated_at` already existed. In both cases the response returns the current persisted state.

**Errors**

* `400` — `Invalid JSON body`
* `400` — `JSON body must be an object`
* `400` — `alert_id must use a supported source and safe source id`
* `400` — `action must be one of: read, resolve, snooze, open`
* `400` — `intent must include a bounded client_updated_at and UUID mutation_id`
* `400` — `snooze_until must be a future ISO timestamp`
* `401` — Unauthorized (no signed-in session)
* `404` — `Alert not found` — alert does not exist or is outside the 14-day eligibility window
* `500` — `Unable to persist alert state`
* `503` — `Unable to verify alert visibility` — source table query failed

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/unified/state \
  -d '{
    "alert_id": "dark:456",
    "action": "resolve",
    "intent": {
      "client_updated_at": "2026-04-18T10:00:00Z",
      "mutation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'
```

***

## Alert rules [#alert-rules]

Define custom rules that filter the unified alert stream using boolean expressions. Rules support nested `and`/`or` groups and can match on product, severity, event type, vessel IMO, or any metadata field. Every rule change is versioned so you can audit who changed what and when.

### `GET` `/api/v1/alerts/rules` [#get-apiv1alertsrules]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of any parameters; the shape below is the intended contract once the feature ships.


List your alert rules.

**Response**

```json
{ "error": "Alert rules is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert rules is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/alerts/rules
```

### `POST` `/api/v1/alerts/rules` [#post-apiv1alertsrules]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the request body; the shape below is the intended contract once the feature ships.


Create a new alert rule.

**Parameters**

| Name                    | Type    | Required | Description                                                        |
| ----------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `name`                  | string  | ✓        | Rule name                                                          |
| `description`           | string  |          | Human-readable description                                         |
| `expression`            | object  | ✓        | Boolean expression tree (see below)                                |
| `severity_override`     | string  |          | Override the alert's severity when this rule matches               |
| `dedupe_window_minutes` | number  |          | Suppress duplicate matches within this window (1–1440, default 60) |
| `active`                | boolean |          | Whether the rule is active (default `true`)                        |

#### Expression format [#expression-format]

Expressions are recursive trees of groups and conditions:

```json
{
  "kind": "group",
  "operator": "and",
  "conditions": [
    { "kind": "condition", "field": "product", "op": "eq", "value": "overwatch" },
    {
      "kind": "group",
      "operator": "or",
      "conditions": [
        { "kind": "condition", "field": "source", "op": "eq", "value": "dark_event" },
        { "kind": "condition", "field": "source", "op": "eq", "value": "spoofing_alert" }
      ]
    }
  ]
}
```

**Supported condition fields**

| Field        | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| `product`    | `overwatch` or `locus`                                             |
| `severity`   | `critical`, `warning`, or `info`                                   |
| `source`     | `platform`, `dark_event`, `spoofing_alert`, `locus_alert`          |
| `event_type` | Alert event type string                                            |
| `entity_id`  | Entity identifier                                                  |
| `imo_number` | 7-digit IMO number                                                 |
| `metadata.*` | Any key in the alert's metadata object (e.g. `metadata.gap_hours`) |

**Supported operators:** `eq`, `neq`, `in`, `contains`, `gte`, `lte`

**Response**

```json
{ "error": "Alert rules is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert rules is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of the body.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/rules \
  -d '{
    "name": "Critical dark events",
    "expression": {
      "kind": "group",
      "operator": "and",
      "conditions": [
        { "kind": "condition", "field": "severity", "op": "eq", "value": "critical" },
        { "kind": "condition", "field": "source", "op": "eq", "value": "dark_event" }
      ]
    },
    "dedupe_window_minutes": 120
  }'
```

### `PATCH` `/api/v1/alerts/rules` [#patch-apiv1alertsrules]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the request body; the shape below is the intended contract once the feature ships.


Update an existing rule. Changes are versioned—pass an optional `notes` field to record why the change was made.

**Parameters**

| Name         | Type    | Required | Description                |
| ------------ | ------- | -------- | -------------------------- |
| `id`         | number  | ✓        | Rule id                    |
| `name`       | string  |          | Updated name               |
| `expression` | object  |          | Updated expression         |
| `active`     | boolean |          | Enable or disable the rule |
| `notes`      | string  |          | Version history note       |

**Response**

```json
{ "error": "Alert rules is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert rules is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of the body.

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/rules \
  -d '{"id": 1, "active": false, "notes": "Pausing during port maintenance window"}'
```

### `DELETE` `/api/v1/alerts/rules` [#delete-apiv1alertsrules]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the 

  `id`

   query param; the shape below is the intended contract once the feature ships.


Delete a rule.

**Parameters**

| Name | Type   | Required | Description           |
| ---- | ------ | -------- | --------------------- |
| `id` | number | ✓        | Rule id (query param) |

**Response**

```json
{ "error": "Alert rules is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert rules is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of `id`.

**Example**

```bash
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/alerts/rules?id=1"
```

### `POST` `/api/v1/alerts/rules/dry-run` [#post-apiv1alertsrulesdry-run]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the request body; the shape below is the intended contract once the feature ships.


Test a rule expression against recent alerts without saving it. Use this to preview how many alerts a rule would match before creating it.

**Parameters**

| Name            | Type    | Required | Description                                 |
| --------------- | ------- | -------- | ------------------------------------------- |
| `expression`    | object  | ✓        | Rule expression to test                     |
| `product`       | string  |          | `all` (default), `overwatch`, or `locus`    |
| `severity`      | string  |          | Filter by severity before evaluation        |
| `watchlistOnly` | boolean |          | Only test against watchlisted vessel alerts |
| `portfolioId`   | string  |          | Scope to a Locus portfolio                  |
| `limit`         | number  |          | Max alerts to evaluate (1–200, default 100) |

**Response**

```json
{ "error": "Alert rules is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert rules is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of the body.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/rules/dry-run \
  -d '{
    "expression": {
      "kind": "group",
      "operator": "and",
      "conditions": [
        { "kind": "condition", "field": "severity", "op": "eq", "value": "critical" },
        { "kind": "condition", "field": "source", "op": "in", "value": ["dark_event", "spoofing_alert"] }
      ]
    },
    "product": "overwatch"
  }'
```

***

## Alert channels [#alert-channels]

Configure where alert notifications are delivered. You can enable multiple channels simultaneously—each channel is independently toggled and tested.

**Supported channels:** Slack, Microsoft Teams, email, and custom webhook.

### `GET` `/api/v1/alerts/channels` [#get-apiv1alertschannels]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

  ; the shape below is the intended contract once the feature ships.


List your configured alert channels. Secrets and webhook URLs are partially masked in the response.

**Response**

```json
{ "error": "Alert delivery channels is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert delivery channels is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/alerts/channels
```

### `PUT` `/api/v1/alerts/channels` [#put-apiv1alertschannels]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the request body; the shape below is the intended contract once the feature ships.


Create or update a channel configuration.

**Parameters**

| Name      | Type    | Required | Description                                |
| --------- | ------- | -------- | ------------------------------------------ |
| `channel` | string  | ✓        | `slack`, `email`, `teams`, or `webhook`    |
| `enabled` | boolean | ✓        | Whether the channel is active              |
| `config`  | object  | ✓        | Channel-specific configuration (see below) |

**Channel configuration**

| Channel   | Config fields                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `slack`   | `webhook_url` — must be a `https://hooks.slack.com/services/...` URL                                      |
| `teams`   | `webhook_url` — any valid HTTPS URL                                                                       |
| `email`   | `to` — comma-separated email addresses                                                                    |
| `webhook` | `url` — HTTPS endpoint; `secret` (optional) — HMAC-SHA256 signing key, sent as `X-Axiom-Signature` header |

**Response**

```json
{ "error": "Alert delivery channels is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert delivery channels is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of the body.

**Example**

```bash
curl -X PUT -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/channels \
  -d '{
    "channel": "slack",
    "enabled": true,
    "config": { "webhook_url": "https://hooks.slack.com/services/T00.../B00.../xxxx" }
  }'
```

### `DELETE` `/api/v1/alerts/channels` [#delete-apiv1alertschannels]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the 

  `channel`

   query param; the shape below is the intended contract once the feature ships.


Remove a channel configuration.

**Parameters**

| Name      | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `channel` | string | ✓        | Channel to remove (query param) |

**Response**

```json
{ "error": "Alert delivery channels is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert delivery channels is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of `channel`.

**Example**

```bash
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/alerts/channels?channel=teams"
```

### `POST` `/api/v1/alerts/channels/test` [#post-apiv1alertschannelstest]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of the request body; the shape below is the intended contract once the feature ships.


Send a test notification through a configured channel. The test message uses sample vessel data so you can verify formatting and delivery.

**Parameters**

| Name      | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `channel` | string | ✓        | `slack`, `email`, `teams`, or `webhook` |

**Response**

```json
{ "error": "Alert delivery channels is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert delivery channels is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today, regardless of the body.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/channels/test \
  -d '{"channel": "slack"}'
```

***

## Alert deliveries [#alert-deliveries]

Track the status of every alert notification sent through your configured channels. The delivery ledger records each attempt, retries with exponential backoff, and moves permanently failed deliveries to a dead-letter queue.

### `GET` `/api/v1/alerts/deliveries` [#get-apiv1alertsdeliveries]


  Requires API key. Currently disabled — this endpoint unconditionally returns 

  `503`

   regardless of any parameters; the shape below is the intended contract once the feature ships.


List recent alert deliveries and any dead-lettered failures.

**Parameters**

| Name      | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `channel` | string |          | Filter by channel type    |
| `status`  | string |          | Filter by delivery status |
| `limit`   | number |          | Default 50, max 200       |

**Response**

```json
{ "error": "Alert delivery history is not launch-supported", "code": "feature_unavailable" }
```

**Errors**

* `503` — `Alert delivery history is not launch-supported` (`code: "feature_unavailable"`) — every request to this endpoint returns this today.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/alerts/deliveries?channel=slack
```


# Backtesting (/overwatch/api/backtesting)



The backtesting API compares Overwatch hydrostatic cargo estimates against ground truth observations from port authority manifests, bills of lading, and customs declarations. Use it to audit estimate accuracy, identify systematic biases by vessel class or route, and calibrate the hydrostatic model. For how the estimates themselves are produced, see the [cargo validation methodology](/overwatch/methodology/cargo-validation).

## `GET` `/api/v1/backtesting/cargo-validation` [#get-apiv1backtestingcargo-validation]


  Requires API key with analyst access.


Runs a full backtesting report over a configurable lookback window. The endpoint matches vessel visits with ground truth records by IMO number and arrival date, then computes error metrics overall and by segment.

**Parameters**

| Name             | Type   | Required | Description                                                                                 |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `lookback_days`  | number |          | Number of days to look back. Default 365, range 30–1095.                                    |
| `max_match_days` | number |          | Maximum day distance when matching a visit to a ground truth record. Default 7, range 1–21. |

**Response**

```json
{
  "generated_at": "2026-04-18T12:00:00Z",
  "window": {
    "from": "2025-04-18T12:00:00Z",
    "to": "2026-04-18T12:00:00Z",
    "lookback_days": 365,
    "max_match_distance_days": 7
  },
  "methodology": {
    "ground_truth_sources": [
      {
        "key": "antaq_vessel_calls",
        "type": "port_authority_manifest",
        "description": "Brazil ANTAQ vessel call records with cargo_tons used as observed cargo proxy."
      },
      {
        "key": "cargo_ground_truth_observations",
        "type": "bill_of_lading/customs_declaration",
        "description": "Externally sourced bill-of-lading and customs declaration observations when available."
      }
    ],
    "matching_rule": {
      "join_key": "imo_number",
      "timing_alignment": "closest observed_at to vessel_visits.arrived_at within 7 days",
      "port_alignment": "port-name fuzzy alignment receives higher ranking"
    },
    "error_metrics": ["MAPE", "MAE", "RMSE", "mean signed error"]
  },
  "ground_truth_source_counts": {},
  "overall_metrics": {
    "sample_size": 847,
    "mape_pct": 12.4,
    "mae_tons": 3200,
    "rmse_tons": 4800,
    "mean_signed_error_tons": -420
  },
  "breakdowns": {
    "vessel_class": [],
    "route": [],
    "cargo_type": [],
    "weather": []
  },
  "trim_salinity_feedback": [],
  "persistence": { "run_id": null, "saved": true, "error": null },
  "matched_rows": []
}
```

`ground_truth_source_counts` maps `":"` (e.g. `"port_authority_manifest:antaq_vessel_calls"`) to the number of matched rows sourced from it.

### Overall metrics [#overall-metrics]

| Field                    | Type   | Description                                                |
| ------------------------ | ------ | ---------------------------------------------------------- |
| `sample_size`            | number | Number of matched visit–ground-truth pairs.                |
| `mape_pct`               | number | Mean absolute percentage error (%).                        |
| `mae_tons`               | number | Mean absolute error in tonnes.                             |
| `rmse_tons`              | number | Root mean squared error in tonnes.                         |
| `mean_signed_error_tons` | number | Average signed error. Positive means estimates trend high. |

### Breakdowns [#breakdowns]

The `breakdowns` object contains the same set of metrics grouped by four dimensions:

* **`vessel_class`** — by vessel type (bulk carrier, tanker, container, etc.)
* **`route`** — by origin–destination country pair
* **`cargo_type`** — by commodity
* **`weather`** — by weather conditions at departure (`calm`, `moderate`, `rough`, `unknown`)

Each breakdown entry includes `bucket`, `sample_size`, `mape_pct`, `mae_tons`, `rmse_tons`, and `mean_signed_error_tons`.

### Trim/salinity feedback [#trimsalinity-feedback]

The `trim_salinity_feedback` array highlights vessel segments where the hydrostatic model shows systematic bias. Each entry includes the observed bias direction and a recommendation for tuning the trim or salinity correction factor. Only segments with at least five matched observations are included.

### Methodology [#methodology]

Each response includes a `methodology` block that documents which ground truth sources were used, how visits were matched, and which error metrics were computed. This makes every backtesting run self-documenting for audit purposes.

### Matched rows [#matched-rows]

Each `matched_rows` entry carries `visit_id`, `imo_number`, `vessel_type`, `commodity`, `route`, `weather_bucket`, `estimated_cargo_hydrostatic`, `actual_cargo_tons`, `error_tons`, `abs_error_tons`, `ape_pct`, `hydrostatic_method`, `hydrostatic_confidence_score`, `ground_truth_source`, `ground_truth_source_type`.

### Persistence [#persistence]

Each backtesting run is saved automatically. The `persistence` block in the response includes a `run_id` you can use to reference the run later, and a `saved` flag indicating whether persistence succeeded.

**Errors**

* `403` — Admin API key required (analyst access: caller must resolve to `internal` or `admin` tier)
* `500` — Database query failed

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/backtesting/cargo-validation?lookback_days=180&max_match_days=5"
```


  For regulated reporting, combine the backtesting report with `/api/v1/forecasts/accuracy` and `/api/v1/calibration` to provide auditors with a complete picture of estimate reliability.



# Berth Utilization (/overwatch/api/berth)



Berth occupancy rates and turnaround times.


  For a per-visit breakdown of how arrival-to-departure time was spent (approach, anchor wait, berth, idle), see [Voyage time allocation](/overwatch/methodology/voyage-time-allocation).


## `GET` `/api/v1/berth-utilization` [#get-apiv1berth-utilization]

Latest berth utilization snapshots.

**Parameters**

| Name   | Type   | Required | Description |
| ------ | ------ | -------- | ----------- |
| `port` | string | ✓        | Port slug   |

**Response**

```json
{
  "berth_utilization": [],
  "tier": "pro"
}
```

Each `berth_utilization` entry carries `port`, `port_name`, `port_country`, `zone_id`, `zone_name`, `snapshot_date`, `occupancy_pct`, `avg_turnaround_hours`, `median_turnaround_hours`, `vessels_served`, `total_tons_handled`, `hours_occupied`, `hours_available`.

**Errors**

* `400` — `port` is required
* `404` — port not found
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/berth-utilization?port=VALUE
```

## `GET` `/api/v1/berth-utilization/weekly` [#get-apiv1berth-utilizationweekly]

Weekly berth utilization trends for a port.

**Parameters**

| Name      | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `port`    | string | ✓        | Port slug          |
| `zone_id` | string |          | Specific zone ID   |
| `weeks`   | number |          | Default 12, max 52 |

**Response**

```json
{
  "port": "",
  "port_name": "",
  "port_country": "",
  "weeks": 12,
  "tier": "pro",
  "berth_utilization_weekly": []
}
```

Each `berth_utilization_weekly` entry carries `zone_id`, `zone_name`, `week_start`, `avg_occupancy_pct`, `avg_turnaround_hours`, `median_turnaround_hours`, `vessels_served`, `total_tons_handled`, `trend_direction`.

**Errors**

* `400` — `?port=` is required
* `404` — port not found
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/berth-utilization/weekly?port=VALUE&zone_id=VALUE
```


# Campaign scoring (/overwatch/api/campaign-score)



Multi-window vessel risk scoring with time-decay weighting and watchlist subscription.

Campaign scores aggregate seven signal types — spoofing, temporal motifs, STS transfers, dark events, destination deceptions, lifecycle changes, and PSC inspections — into a single 0–1 risk score per vessel. Scores are computed across 30, 90, and 180-day windows with exponential time decay so recent activity weighs more heavily.

## `GET` `/api/v1/vessels/{imo}/campaign-score` [#get-apiv1vesselsimocampaign-score]


  No API key or session required — this endpoint is unauthenticated.


Get the campaign risk score for a vessel.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

**Response**

```json
{
  "imo": 9876543,
  "score": {
    "overall_score": 0.64,
    "risk_level": "high",
    "window_30": 0.72,
    "window_90": 0.64,
    "window_180": 0.51,
    "reference_date": "2026-04-18T00:00:00Z"
  },
  "isSubscribed": true
}
```

`imo` is returned as a number, and `score` is `null` when no campaign score has been computed yet for the vessel.

**Errors**

* `400` — Invalid IMO number format
* `500` — Database error retrieving the campaign score

### Risk levels [#risk-levels]

| Level    | Score range | Description                                 |
| -------- | ----------- | ------------------------------------------- |
| critical | > 0.75      | Multiple corroborated high-severity signals |
| high     | 0.50 – 0.75 | Significant recent risk activity            |
| medium   | 0.25 – 0.50 | Moderate or aging signals                   |
| low      | \< 0.25     | Minimal risk indicators                     |

### Signal weights [#signal-weights]

Each signal type contributes differently to the aggregate score:

| Signal type           | Weight |
| --------------------- | ------ |
| Spoofing alert        | 0.80   |
| Destination deception | 0.70   |
| Temporal motif        | 0.60   |
| STS transfer          | 0.50   |
| Dark event            | 0.40   |
| Lifecycle change      | 0.30   |
| PSC inspection        | 0.20   |

Severity multipliers (low = 0.5×, medium = 1×, high = 1.5×, critical = 2×) and signal confidence also factor into the final score.

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/campaign-score
```

## `POST` `/api/v1/vessels/{imo}/campaign-score` [#post-apiv1vesselsimocampaign-score]


  Requires a signed-in dashboard session (Supabase auth cookie) — not an API key.


Subscribe or unsubscribe a vessel to your watchlist directly from the campaign score view.

**Parameters**

| Name           | Type   | Required | Description                                                                            |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `imo`          | string | ✓        | 7-digit IMO number (path param)                                                        |
| `action`       | string | ✓        | 'subscribe' or 'unsubscribe'                                                           |
| `watchlist_id` | string |          | Target watchlist. Must be owned by the caller. Creates "Default Watchlist" if omitted. |

**Response**

```json
{ "success": true }
```

**Errors**

* `400` — Invalid IMO number format
* `400` — `watchlist_id` is empty
* `400` — `action` must be `subscribe` or `unsubscribe`
* `401` — Unauthorized (no signed-in session)
* `403` — Forbidden (`watchlist_id` not owned by the caller)
* `404` — Watchlist not found
* `500` — Database error (score fetch, watchlist create/update)

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/campaign-score \
  -d '{"action":"subscribe"}'
```


# Investigation case files (/overwatch/api/case-files)



Structured investigation dossiers built from temporal graph motifs and corroborating evidence.

Case files aggregate multiple signal types into a single narrative per vessel — dark events, spoofing alerts, STS transfers, destination deceptions, and more. Use them to build investigation workflows, export reports for regulatory handoff, or track case status across your team.

## `GET` `/api/v1/vessels/{imo}/case-files` [#get-apiv1vesselsimocase-files]


  Requires API key with analyst access. 

  **Currently returns `503 feature_unavailable` for every request**

   — the investigation case files data model has not been deployed to this launch environment.


Returns investigation case files for a vessel. Each case file is anchored to a temporal graph motif alert and includes all corroborating evidence, an auto-generated narrative, and analyst annotations.

**Parameters**

| Name     | Type   | Required | Description                         |
| -------- | ------ | -------- | ----------------------------------- |
| `imo`    | string | ✓        | 7-digit IMO number (path param)     |
| `cursor` | number |          | Pagination offset (default 0)       |
| `limit`  | number |          | Results per page, 1–25 (default 10) |

**Response**

```json
{
  "error": "Investigation case files is not launch-supported",
  "code": "feature_unavailable"
}
```

This is the complete response body currently returned (HTTP 503) for every request, regardless of the parameters above — no `case_files` array is produced. The shape below reflects the intended design once the feature ships.

**Errors**

* `503` (`feature_unavailable`) — Returned unconditionally: "Investigation case files is not launch-supported"

### Evidence kinds [#evidence-kinds]

Each timeline entry has a `kind` field indicating the evidence type:

| Kind                     | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `dark_event`             | AIS gap or transmission loss                   |
| `spoofing`               | Kinematic or multi-source AIS anomaly          |
| `sts_transfer`           | Ship-to-ship cargo transfer                    |
| `destination_deception`  | Declared destination does not match trajectory |
| `lifecycle_change`       | Flag, name, or MMSI change                     |
| `psc_inspection`         | Port state control detention or deficiency     |
| `cargo_anomaly`          | Draft-based cargo estimation anomaly           |
| `obfuscation_assessment` | Deliberate identity or track obfuscation       |

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/case-files
```

## `PATCH` `/api/v1/vessels/{imo}/case-files` [#patch-apiv1vesselsimocase-files]


  Requires API key with analyst access. 

  **Currently returns `503 feature_unavailable` for every request**

   — the investigation case files data model has not been deployed to this launch environment.


Update annotations on a case file. Use this to change case status, add analyst notes, or set custom export fields for PDF generation and regulatory handoff.

**Parameters**

| Name              | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `imo`             | string | ✓        | 7-digit IMO number (path param)                           |
| `case_id`         | string | ✓        | Case file identifier                                      |
| `motif_alert_id`  | string | ✓        | Associated motif alert identifier                         |
| `status`          | string |          | 'open', 'reviewing', 'escalated', 'reported', or 'closed' |
| `summary`         | string |          | Analyst-provided summary                                  |
| `notes`           | string |          | Free-form investigation notes                             |
| `export_title`    | string |          | Custom title for PDF export                               |
| `export_summary`  | string |          | Custom summary for PDF export                             |
| `handoff_context` | string |          | Context for handoff to another analyst or agency          |

**Response**

```json
{
  "error": "Investigation case files is not launch-supported",
  "code": "feature_unavailable"
}
```

This is the complete response body currently returned (HTTP 503) for every request, regardless of the parameters above. The shape below reflects the intended design once the feature ships.

**Errors**

* `503` (`feature_unavailable`) — Returned unconditionally: "Investigation case files is not launch-supported"

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/case-files \
  -d '{"case_id":"CASE-ABCD-123456789012","motif_alert_id":"alert-xyz","status":"escalated","handoff_context":"Referred to compliance team"}'
```


# Congestion (/overwatch/api/congestion)



Port congestion indices and wait time trends.

## `GET` `/api/v1/congestion` [#get-apiv1congestion]

Latest congestion snapshot for all ports or a specific port.

**Parameters**

| Name          | Type   | Required | Description           |
| ------------- | ------ | -------- | --------------------- |
| `port`        | string | ✓        | Port slug             |
| `vessel_type` | string |          | Filter by vessel type |

**Response**

```json
{
  "tier": "pro",
  "congestion": []
}
```

Each `congestion` entry carries `port`, `port_name`, `port_country`, `vessel_type`, `vessels_waiting`, `avg_wait_hours`, `median_wait_hours`, `p90_wait_hours`, `trend_direction`, `trend_consecutive_periods`, `computed_at`.

**Errors**

* `400` — `port` is required
* `404` — Port not found

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/congestion?port=VALUE&vessel_type=VALUE
```

## `GET` `/api/v1/congestion/history` [#get-apiv1congestionhistory]

Historical congestion data for a port.

**Parameters**

| Name          | Type   | Required | Description           |
| ------------- | ------ | -------- | --------------------- |
| `port`        | string | ✓        | Port slug             |
| `days`        | number |          | Default 30, max 365   |
| `vessel_type` | string |          | Filter by vessel type |

**Response**

```json
{
  "port": "santos",
  "port_name": "Port of Santos",
  "days": 30,
  "vessel_type": null,
  "tier": "pro",
  "history": []
}
```

Each `history` entry carries `date`, `avg_wait_hours`, `median_wait_hours`, `p90_wait_hours`, `vessel_count`.

**Errors**

* `400` — `port` parameter is required
* `404` — Port not found

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/congestion/history?port=VALUE&days=VALUE
```

## `POST` `/api/v1/congestion/refresh` [#post-apiv1congestionrefresh]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Trigger congestion index recomputation.

**Response**

```json
{
  "success": true,
  "result": {}
}
```

**Errors**

* `429` — Congestion index was computed recently (5-minute cooldown; response includes `last_computed_at` and `retry_after_seconds`, and a `Retry-After` header)
* `500` — Supabase credentials not configured
* `502` — The compute-congestion-index Edge Function returned a non-OK status
* `500` — Unexpected error invoking the Edge Function

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/congestion/refresh \
  -d '{"key":"value"}'
```


# Density (/overwatch/api/density)



Global vessel density at H3 resolution 8 (\~0.74 km² per cell), bucketed by day and vessel type. The underlying matview is sourced from `ais_positions` joined to `vessels.vessel_type`, with per-IMO-per-hour bucketing so that vessels broadcasting every 10 seconds don't drown out vessels broadcasting hourly.

The matview holds a rolling 30-day window and is refreshed nightly at **02:00 UTC**, after the previous day's bucket has closed. Use `GET /api/v1/density` to render heatmaps, identify traffic corridors, or surface where a given vessel class is concentrated on a specific day.

## `GET` `/api/v1/density` [#get-apiv1density]

H3 cells with vessel density for a given vessel type and day, ordered by `positions_count` descending.

**Parameters**

| Name    | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`  | string |          | Vessel type filter. Default `bulk_carrier`. There is **no** `all` aggregate — the matview is keyed per `(h3_index, vessel_type, day)`, so an unfiltered pull would return duplicate per-type cells rather than a true union; the route always filters on a single vessel type. Common values: `bulk_carrier`, `tanker`, `container`, `lng_carrier`, `chemical_tanker`, `general_cargo`, `cargo`, `passenger`, `fishing`, `service`, `other` |
| `day`   | string |          | ISO date (`YYYY-MM-DD`). Defaults to yesterday in UTC — the most recent closed-day bucket the matview will have populated                                                                                                                                                                                                                                                                                                                   |
| `limit` | number |          | Cells per response. Default 1,000. Clamped to your tier's per-call ceiling (free/public 20, starter 100, pro 500, admin 10,000), then hard-capped at 1,000 regardless of tier — PostgREST truncates `TABLE` responses at 1,000 rows on this project, so a higher tier limit is unreachable here.                                                                                                                                            |

**Response**

```json
{
  "day": "2026-04-28",
  "vessel_type": "bulk_carrier",
  "cells": [],
  "count": 0,
  "tier": "starter"
}
```

Each `cells` entry carries `h3_index`, `vessel_type`, `positions_count`, `unique_vessels`:

* `h3_index` — H3 resolution-8 cell ID (\~0.74 km²)
* `positions_count` — distinct per-IMO-per-hour position records that fell in this cell on this day
* `unique_vessels` — distinct IMOs that pinged inside this cell on this day

**Errors**

* `500` — Internal server error (matview query failed)

**Example**

```bash
curl https://www.axiomoverwatch.io/api/v1/density?type=bulk_carrier&day=2026-04-28
```

```bash
# A different vessel type, with an explicit (tier-bounded) limit
curl https://www.axiomoverwatch.io/api/v1/density?type=tanker&day=2026-04-28&limit=500
```

## Freshness [#freshness]

Every response reflects the matview as of its most recent successful refresh. The dashboard surface at `/dashboard/density` displays the last refresh timestamp and status (`ok` or otherwise) sourced from the `derived_views_freshness` ledger. If you need to programmatically detect a stale matview before consuming density data, request a recent `day` and check that `count` is non-zero.

If the latest scheduled refresh failed, the most recent closed day may not yet be queryable — fall back to the prior day until the ledger reports `ok`.


# Disruptions (/overwatch/api/disruptions)



GDELT-sourced news signals about commodity trade disruptions.

## `GET` `/api/v1/disruptions` [#get-apiv1disruptions]


  Requires API key.


Real-time disruption signals from global news: port closures, sanctions, trade disputes, weather events, canal blockages.

**Parameters**

| Name     | Type   | Required | Description                                                                                                        |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `hours`  | number |          | Lookback window in hours (default 24)                                                                              |
| `query`  | string |          | Title text filter                                                                                                  |
| `cursor` | string |          | Opaque pagination cursor — pass the `next_cursor` value from a previous page (a `published_at` timestamp boundary) |
| `limit`  | number |          | Default 20. Clamped to your tier's per-call ceiling: free/public 20, starter 100, pro 500, admin 10,000.           |

**Response**

```json
{
  "signals": [],
  "count": 0,
  "timespan_hours": 24,
  "tier": "pro",
  "pagination": { "limit": 20, "has_more": false, "next_cursor": null }
}
```

Each `signals` entry carries `title`, `url`, `source_name`, `published_at`, `tone`, `search_query`, `image_url`.

**Errors**

* `500` — Internal server error (query failed)

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/disruptions?hours=VALUE&query=VALUE
```


# Earnings & Freight (/overwatch/api/earnings)



Voyage earnings estimates and freight rate data.

## `GET` `/api/v1/earnings` [#get-apiv1earnings]

Per-voyage earnings estimates.

**Parameters**

| Name     | Type   | Required | Description                                                                                          |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `vessel` | string |          | IMO number (5–8 digits)                                                                              |
| `port`   | string | ✓        | Port slug                                                                                            |
| `cursor` | string |          | Pagination cursor — the `created_at` value of the last row from the previous page                    |
| `limit`  | number |          | Default 50. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "tier": "pro",
  "earnings": [],
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `earnings` entry carries `id`, `imo_number`, `vessel_name`, `vessel_flag`, `port`, `port_name`, `port_country`, `estimated_cargo_tons`, `freight_rate_per_ton`, `gross_revenue_usd`, `vessel_type`, `rate_source`, `rate_date`, `created_at`.

**Errors**

* `400` — `port` is required
* `400` — Invalid IMO number (when `vessel` fails the 5–8 digit check)
* `404` — Port not found
* `500` — Internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/earnings?vessel=VALUE&port=VALUE
```

## `GET` `/api/v1/earnings/port-revenue` [#get-apiv1earningsport-revenue]

Weekly port revenue aggregates.

**Parameters**

| Name     | Type   | Required | Description                                                                                          |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `port`   | string | ✓        | Port slug                                                                                            |
| `cursor` | number |          | Pagination offset (default 0)                                                                        |
| `limit`  | number |          | Default 52. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "tier": "pro",
  "port_revenue": [],
  "pagination": { "limit": 52, "has_more": false, "next_cursor": null }
}
```

Each `port_revenue` entry carries `id`, `port`, `port_name`, `port_country`, `week_start`, `vessel_count`, `total_tons`, `total_revenue_usd`, `avg_rate_per_ton`, `commodity`.

**Errors**

* `400` — `port` is required
* `404` — Port not found
* `500` — Internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/earnings/port-revenue?port=VALUE&limit=VALUE
```

## `GET` `/api/v1/freight-rates` [#get-apiv1freight-rates]

Freight rate data by vessel type.

**Parameters**

| Name          | Type   | Required | Description                                                                                          |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `vessel_type` | string |          | Vessel type filter                                                                                   |
| `cursor`      | number |          | Pagination offset (default 0)                                                                        |
| `limit`       | number |          | Default 50. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "freight_rates": [],
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `freight_rates` entry carries `id`, `vessel_type`, `route`, `rate_per_ton`, `currency`, `rate_date`, `source`, `index_name`, `index_value`, `created_at`, `updated_at`.

**Errors**

* `500` — Internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/freight-rates?vessel_type=VALUE&limit=VALUE
```

## `POST` `/api/v1/freight-rates` [#post-apiv1freight-rates]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Submit a new freight rate record.

**Parameters**

| Name           | Type   | Required | Description                           |
| -------------- | ------ | -------- | ------------------------------------- |
| `vessel_type`  | string | ✓        | Vessel type                           |
| `route`        | string |          | Route identifier                      |
| `rate_per_ton` | number | ✓        | Rate per ton (must be non-negative)   |
| `currency`     | string |          | Default `USD`                         |
| `rate_date`    | string | ✓        | Rate date                             |
| `source`       | string | ✓        | One of `manual`, `api`, `bdi_derived` |
| `index_name`   | string |          | Index name                            |
| `index_value`  | number |          | Index value                           |

**Response**

```json
{
  "freight_rate": {}
}
```

Returned with status `201`. The `freight_rate` object carries `id`, `vessel_type`, `route`, `rate_per_ton`, `currency`, `rate_date`, `source`, `index_name`, `index_value`, `created_at`.

**Errors**

* `400` — Invalid request body
* `400` — `vessel_type, rate_per_ton, rate_date, and source are required`
* `400` — `source must be one of: manual, api, bdi_derived`
* `400` — `rate_per_ton must be a non-negative number`
* `401` — Unauthorized
* `403` — Admin access not configured
* `429` — Too many auth attempts
* `500` — Internal server error

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/freight-rates \
  -d '{"key":"value"}'
```


# Emissions (/overwatch/api/emissions)



Scope 3 maritime emissions accounting and disclosure-ready exports.

## `GET` `/api/v1/emissions` [#get-apiv1emissions]


  Requires API key.


Per-voyage and fleet-level CO2 estimates using ton-mile model with uncertainty bounds.

**Parameters**

| Name          | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `port`        | string | ✓        | Port slug (400 if missing, 404 if unknown)                                                            |
| `imo`         | string |          | Filter by vessel IMO                                                                                  |
| `start`       | string |          | ISO start timestamp                                                                                   |
| `end`         | string |          | ISO end timestamp                                                                                     |
| `fuel_type`   | string |          | 'vlsfo' \| 'mgo' \| 'lng' \| 'methanol' (defaults to 'vlsfo' if omitted or unrecognized)              |
| `distance_nm` | number |          | Assumed voyage distance in nautical miles (default 1200)                                              |
| `speed_knots` | number |          | Assumed speed for intensity model (default 14)                                                        |
| `group_by`    | string |          | 'none' \| 'imo' \| 'port' \| 'commodity'                                                              |
| `format`      | string |          | 'json' (default) or 'csv'                                                                             |
| `cursor`      | string |          | Cursor offset for pagination                                                                          |
| `limit`       | number |          | Default 50, clamped to the caller's tier ceiling (20 free/public, 100 starter, 500 pro, 10,000 admin) |

**Response**

```json
{
  "tier": "pro",
  "assumptions": {
    "fuel_type": "vlsfo",
    "speed_knots": 14,
    "distance_nm": 1200,
    "model_version": "v1-ton-mile"
  },
  "fleet": {},
  "grouped": [],
  "voyages": [],
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `voyages` entry carries `visit_id`, `imo_number`, `port`, `port_name`, `commodity`, `arrived_at`, `departed_at`, `cargo_tons`, `distance_nm`, `vessel_class`, `fuel_type`, `co2_kg`, `co2_tonnes`, `co2_per_ton_mile_kg`, `co2_kg_low`, `co2_kg_high`, `uncertainty_pct`. `grouped` is only populated when `group_by` is not `none`. When `format=csv`, the response is a CSV attachment of the `voyages` rows instead of the JSON envelope above.

**Errors**

* `400` — `port` is required
* `404` — Port not found
* `500` — Internal server error

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/emissions?imo=VALUE&port=VALUE
```

## `GET` `/api/v1/emissions/report` [#get-apiv1emissionsreport]


  Requires API key.


CSRD / SEC Scope 3 report export in JSON, CSV, or PDF format.

**Parameters**

| Name          | Type   | Required | Description                                                                                            |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `port`        | string | ✓        | Port slug (400 if missing, 404 if unknown)                                                             |
| `entity`      | string |          | Reporting entity name (default "Unknown reporting entity")                                             |
| `start`       | string |          | ISO start timestamp (default 30 days ago)                                                              |
| `end`         | string |          | ISO end timestamp (default now)                                                                        |
| `imo`         | string |          | Filter by vessel IMO                                                                                   |
| `fuel_type`   | string |          | 'vlsfo' \| 'mgo' \| 'lng' \| 'methanol' (defaults to 'vlsfo' if omitted or unrecognized)               |
| `distance_nm` | number |          | Assumed voyage distance in nautical miles (default 1200)                                               |
| `speed_knots` | number |          | Assumed speed for intensity model (default 14, floored at 8)                                           |
| `format`      | string |          | 'json' (default), 'csv', or 'pdf'                                                                      |
| `cursor`      | string |          | Cursor offset for pagination                                                                           |
| `limit`       | number |          | Default 200, clamped to the caller's tier ceiling (20 free/public, 100 starter, 500 pro, 10,000 admin) |

**Response**

```json
{
  "tier": "pro",
  "report": {
    "reporting_entity": "Unknown reporting entity",
    "reporting_period_start": "2026-03-01T00:00:00.000Z",
    "reporting_period_end": "2026-04-01T00:00:00.000Z",
    "framework": "CSRD|SEC Climate",
    "scope_category": "Scope 3",
    "scope_subcategory": "3.4 upstream transportation and distribution",
    "methodology": "ton-mile model",
    "model_version": "v1-ton-mile",
    "assumptions": { "fuel_type": "vlsfo", "speed_knots": 14, "distance_nm": 1200 },
    "totals": {}
  },
  "voyages": [],
  "pagination": { "limit": 200, "has_more": false, "next_cursor": null }
}
```

`report.totals` holds the aggregate fleet CO2 summary. Each `voyages` entry carries `reporting_framework`, `scope_category`, `scope_subcategory`, `visit_id`, `imo_number`, `departed_at`, `port`, `port_name`, `commodity`, `cargo_tons`, `distance_nm`, `vessel_class`, `fuel_type`, `co2_tonnes`, `co2_tonnes_low`, `co2_tonnes_high`, `uncertainty_pct`. When `format=csv`, returns a CSV attachment (summary header + row detail); when `format=pdf`, returns a PDF attachment. Otherwise returns the JSON envelope above.

**Errors**

* `400` — `port` is required
* `404` — Port not found
* `500` — Internal server error

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/emissions/report?entity=VALUE&start=VALUE
```


# Export Estimates (/overwatch/api/estimates)



Weekly aggregated cargo volume predictions by port.

## `GET` `/api/v1/estimates` [#get-apiv1estimates]

Weekly export volume estimates with vessel count, tonnage, confidence, and USDA actuals.

**Parameters**

| Name     | Type   | Required | Description                                                                                                                                              |
| -------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`   | string | ✓        | Port slug                                                                                                                                                |
| `cursor` | string |          | Opaque pagination cursor — pass the `next_cursor` value from a previous page (a `week_start` date boundary)                                              |
| `limit`  | number |          | Default 52. Clamped to your tier's per-call ceiling: free/public 20, starter 100, pro 500, admin 10,000 — a lower tier ceiling overrides the 52 default. |

**Response**

```json
{
  "estimates": [],
  "tier": "pro",
  "pagination": { "limit": 52, "has_more": false, "next_cursor": null }
}
```

Each `estimates` entry carries `port`, `port_name`, `week_start`, `week_end`, `vessel_count`, `estimated_tons`, `estimate_mid`, `estimate_low`, `estimate_high`, `coverage_level`, `avg_draft_change`, `commodity`, `confidence`, `model_eval` (`mae`, `crps`, `empirical_coverage`, or `null`), `usda_actual`.

**Errors**

* `400` — `port` is required
* `404` — Port not found
* `500` — Failed to load estimates

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/estimates?port=VALUE&limit=VALUE
```


# Data Export (/overwatch/api/export)



Download data as CSV files.

## `GET` `/api/v1/export` [#get-apiv1export]


  Requires API key.


Export visits or estimates as CSV. Requires a paid tier (`starter`, `pro`, or `admin`) — free/public keys get a 403.

**Parameters**

| Name     | Type   | Required | Description                                                                                                                                                                                       |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`   | string | ✓        | Port slug                                                                                                                                                                                         |
| `type`   | string |          | 'visits' \| 'estimates' (default: visits)                                                                                                                                                         |
| `cursor` | number |          | Row offset for pagination (default 0). A plain 0-based row index into the result set, not a timestamp — use the value echoed in the `X-Pagination-Next-Cursor` response header for the next page. |
| `limit`  | number |          | Default 100. Clamped to your tier's per-call ceiling: starter 100, pro 500, admin 10,000 (free/public cannot call this endpoint at all — see Errors).                                             |

**Response**

CSV file (`Content-Type: text/csv`). Pagination state is returned via response headers: `X-Pagination-Limit`, `X-Pagination-Has-More`, `X-Pagination-Next-Cursor`.

**Errors**

* `400` — `port` is required
* `400` — Unsupported export type (must be `visits` or `estimates`)
* `403` — CSV export requires a paid tier
* `404` — Port not found

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/export?port=VALUE&type=VALUE
```


# Fleet Age (/overwatch/api/fleet)



Fleet age demographics and aging vessel risk.

## `GET` `/api/v1/fleet-age` [#get-apiv1fleet-age]


  Requires API key.


Fleet age statistics by port, including age buckets and risk percentages.

**Parameters**

| Name          | Type   | Required | Description                                                                                               |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `port`        | string | ✓        | Port slug (400 if missing, 404 if unknown)                                                                |
| `vessel_type` | string |          | Vessel type filter. Omit to get only the fleet-wide rows (`vessel_type IS NULL`), not all types combined. |

**Response**

```json
{
  "tier": "pro",
  "fleet_age": []
}
```

Each `fleet_age` entry carries `port`, `port_name`, `port_country`, `vessel_type`, `vessel_count`, `avg_age_years`, `median_age_years`, `pct_over_15y`, `pct_over_20y`, `pct_over_30y`, `old_fleet_risk_event_pct`, `age_buckets`, `computed_at`.

**Errors**

* `400` — `port` is required
* `404` — Port not found
* `500` — Internal server error

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl -X GET -H "X-API-Key: YOUR_KEY" \
      "https://www.axiomoverwatch.io/api/v1/fleet-age?port=santos&vessel_type=bulk_carrier"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/fleet-age",
        params={"port": "santos", "vessel_type": "bulk_carrier"},
        headers={"X-API-Key": "YOUR_KEY"},
    )
    data = res.json()  # {"tier": "pro", "fleet_age": [...]}
    ```
  

  
    ```js
    const url = new URL("https://www.axiomoverwatch.io/api/v1/fleet-age");
    url.searchParams.set("port", "santos");
    url.searchParams.set("vessel_type", "bulk_carrier");

    const data = await fetch(url, {
      headers: { "X-API-Key": "YOUR_KEY" },
    }).then((r) => r.json());
    ```
  


## `GET` `/api/v1/fleet-age/history` [#get-apiv1fleet-agehistory]


  Requires API key.


Weekly fleet age trends for a port.

**Parameters**

| Name          | Type   | Required | Description                                                                                                             |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `port`        | string | ✓        | Port slug (400 if missing, 404 if unknown)                                                                              |
| `vessel_type` | string |          | Vessel type filter. Omit to get only the fleet-wide rows (`vessel_type IS NULL`), not all types combined.               |
| `weeks`       | number |          | Default 12, max 52. Also clamped to the caller's tier history window (`maxHistoryDays`), whichever is more restrictive. |

**Response**

```json
{
  "port": "santos",
  "port_name": "Port of Santos",
  "weeks": 12,
  "vessel_type": null,
  "tier": "pro",
  "history": []
}
```

Each `history` entry carries `week_start`, `avg_age_years`, `pct_over_20y`, `vessel_count`.

**Errors**

* `400` — `port` parameter is required
* `404` — Port not found
* `500` — Internal server error

**Example**


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    curl -X GET -H "X-API-Key: YOUR_KEY" \
      "https://www.axiomoverwatch.io/api/v1/fleet-age/history?port=santos&weeks=12"
    ```
  

  
    ```python
    import requests

    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/fleet-age/history",
        params={"port": "santos", "weeks": 12},
        headers={"X-API-Key": "YOUR_KEY"},
    )
    data = res.json()  # {"port": "santos", "weeks": 12, "history": [...]}
    ```
  

  
    ```js
    const url = new URL("https://www.axiomoverwatch.io/api/v1/fleet-age/history");
    url.searchParams.set("port", "santos");
    url.searchParams.set("weeks", "12");

    const data = await fetch(url, {
      headers: { "X-API-Key": "YOUR_KEY" },
    }).then((r) => r.json());
    ```
  



# Forecasts (/overwatch/api/forecasts)



Cargo volume forecasts and accuracy tracking.

## `GET` `/api/v1/forecasts` [#get-apiv1forecasts]

Cargo volume forecasts by port and methodology.

**Parameters**

| Name         | Type    | Required | Description                                                                                                                                           |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`       | string  | ✓        | Port slug                                                                                                                                             |
| `method`     | string  |          | 'pipeline' \| 'statistical' \| 'ml'                                                                                                                   |
| `limit`      | number  |          | Default 50, clamped to the API key's tier ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin)                                          |
| `cursor`     | string  |          | Pagination cursor — pass the previous response's `pagination.next_cursor` (a `target_week_start` value) to fetch forecasts with an earlier week start |
| `include_ml` | boolean |          | Reveal hidden ML-method forecasts (billing-gated). Default `false`                                                                                    |

**Response**

```json
{
  "tier": "pro",
  "forecasts": [],
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `forecasts` entry carries `id`, `port`, `port_name`, `port_country`, `commodity`,
`forecast_method`, `target_week_start`, `forecast_date`, `predicted_tons`, `predicted_vessels`,
`confidence_low`, `confidence_high`, `actual_tons`, `actual_vessels`, `accuracy_pct`,
`model_version`, `is_visible`, `metadata`, `created_at`.

**Errors**

* `400` — `port` missing
* `404` — port slug not found
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/forecasts?port=VALUE&method=VALUE
```

## `GET` `/api/v1/forecasts/accuracy` [#get-apiv1forecastsaccuracy]

Forecast accuracy metrics (MAE, MAPE, directional accuracy).

**Parameters**

| Name     | Type   | Required | Description     |
| -------- | ------ | -------- | --------------- |
| `port`   | string | ✓        | Port slug       |
| `method` | string |          | Forecast method |

**Response**

```json
{
  "tier": "pro",
  "accuracy": []
}
```

Each `accuracy` entry carries `port`, `port_name`, `port_country`, `commodity`,
`forecast_method`, `rolling_8week_mae`, `rolling_8week_mape`, `directional_accuracy_pct`,
`total_forecasts`, `ml_is_visible`, `computed_at`.

**Errors**

* `400` — `port` missing
* `404` — port slug not found
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/forecasts/accuracy?port=VALUE&method=VALUE
```

## `POST` `/api/v1/predict-destination` [#post-apiv1predict-destination]


  Requires API key.


Predict the next destination port for a vessel from its recent movement pattern. The model consumes an ordered sequence of H3 cells the vessel has passed through and, optionally, draft changes that hint at loading or discharge events. Use this when you need a live forward-looking guess — for example, to populate an ETA widget, rank which vessels to investigate next, or enrich a dashboard where the AIS-reported destination is missing or unreliable.

Pair this endpoint with `GET /api/v1/destination-reliability` to decide whether to trust the vessel's declared destination or fall back to the model prediction.

**Body**

| Name                 | Type      | Required | Description                                                                                   |
| -------------------- | --------- | -------- | --------------------------------------------------------------------------------------------- |
| `mmsi`               | string    | ✓        | Vessel MMSI                                                                                   |
| `active_h3_sequence` | string\[] | ✓        | Ordered list of H3 cell indexes the vessel has moved through, oldest first. Up to 256 entries |
| `draft_current`      | number    |          | Current reported draft in meters                                                              |
| `draft_delta`        | number    |          | Change in draft since start of the sequence, in meters                                        |

Request payloads are capped at 32 KB.

**Response**

```json
{
  "predictions": [
    { "port": "sgsin", "probability": 0.42 },
    { "port": "mypkg", "probability": 0.19 },
    { "port": "idjkt", "probability": 0.11 }
  ]
}
```

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/predict-destination \
  -d '{
    "mmsi": "563123456",
    "active_h3_sequence": ["8a2a1072b59ffff", "8a2a1072b58ffff", "8a2a1072b41ffff"],
    "draft_current": 12.4,
    "draft_delta": -0.8
  }'
```

## `GET` `/api/v1/destination-reliability` [#get-apiv1destination-reliability]

Vessel destination declaration reliability scores.

**Parameters**

| Name     | Type   | Required | Description                                                                                                                              |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `vessel` | string |          | IMO number                                                                                                                               |
| `tier`   | string |          | 'reliable' \| 'moderate' \| 'unreliable'                                                                                                 |
| `limit`  | number |          | Default 100, clamped to the API key's tier ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin)                            |
| `cursor` | string |          | Pagination cursor — pass the previous response's `pagination.next_cursor` (a `reliability_score` value) to fetch rows with a lower score |

**Response**

```json
{
  "reliability": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `reliability` entry returns the full `vessel_destination_reliability` row plus a nested
`vessel` object with `imo_number`, `name`, `vessel_type`, `flag`.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/destination-reliability?vessel=VALUE&tier=VALUE
```


# Insurance underwriting (/overwatch/api/insurance)



Use Overwatch risk intelligence to inform marine insurance underwriting decisions. These endpoints combine vessel risk scores, PSC inspection history, dark fleet activity, and sanctions exposure into actuarial-grade outputs.

## `GET` `/api/v1/insurance/claims-prediction` [#get-apiv1insuranceclaims-prediction]


  Requires API key with analyst access.


Predict the claims probability for a vessel based on its risk profile, age, inspection history, and dark fleet involvement. Returns a probability score and the contributing risk factors.

**Parameters**

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `imo` | string | ✓        | 7-digit IMO number |

**Response**

```json
{
  "imo_number": "9622629",
  "vessel_name": "MV Meridian",
  "generated_at": "2026-07-23T00:00:00.000Z",
  "model_version": "claims-proxy-2026-04-v1",
  "training_data": {
    "source_table": "psc_inspections",
    "incident_proxy": "detained=true OR deficiencies_found>=10",
    "cohort_peer_count": 48,
    "observations": 612,
    "incident_observations": 41,
    "annual_base_rate": 0.0684
  },
  "features": {
    "risk_score": 42,
    "risk_tier": "medium",
    "sanctions_matches": 0,
    "detained_inspections_12m": 0,
    "deficiencies_per_inspection_12m": 3,
    "dark_events_90d": 1,
    "age_bucket": "11-20"
  },
  "premium_adjustment_factor": 1.15,
  "prediction": {
    "annualProbability": 0.18,
    "sixMonthProbability": 0.0942,
    "threeMonthProbability": 0.0483
  }
}
```

Top-level fields are `imo_number`, `vessel_name`, `generated_at`, `model_version`, `training_data`, `features`, `premium_adjustment_factor`, `prediction`. Note `prediction`'s three sub-fields are camelCase (`annualProbability`, `sixMonthProbability`, `threeMonthProbability`) — everything else in the response is snake\_case.

**Errors**

* `402` — Insurance claims prediction requires a paid analyst plan (caller's tier is not `pro`, `admin`, `supply_chain_risk`, or `professional`)
* `400` — Invalid IMO number - must be exactly 7 digits.
* `404` — Vessel not found.
* `500` — Internal server error

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/insurance/claims-prediction?imo=9622629"
```

## `GET` `/api/v1/insurance/comparable-pool` [#get-apiv1insurancecomparable-pool]


  Requires API key with analyst access.


Find comparable vessels for benchmarking — same type, similar age and DWT range — and see how the focal vessel's risk profile compares to the pool.

**Parameters**

| Name    | Type   | Required | Description                                                                                                                        |
| ------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `imo`   | string | ✓        | 7-digit IMO number                                                                                                                 |
| `limit` | number |          | Number of comparable vessels. Default 50. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "focal_vessel": {
    "imo_number": "9622629",
    "name": "MV Meridian",
    "vessel_type": "Bulk Carrier",
    "build_year": 2012,
    "flag": "Panama",
    "dwt": 82000,
    "registered_owner": "Example Shipping Ltd",
    "ship_manager": "Example Ship Management",
    "risk_score": 42,
    "risk_tier": "medium",
    "age_bucket": "11-20"
  },
  "cohort_definition": {
    "vessel_type": "Bulk Carrier",
    "build_year_window": [2007, 2017],
    "dwt_window": [57400, 106600]
  },
  "cohort_summary": {
    "peer_count": 48,
    "risk_score_avg": 34.2,
    "risk_score_median": 31,
    "same_flag_count": 6,
    "critical_tier_count": 2
  },
  "peers": []
}
```

Each `peers` entry carries `imo_number`, `name`, `vessel_type`, `build_year`, `flag`, `dwt`, `registered_owner`, `ship_manager`, `risk_score`, `risk_tier`.

**Errors**

* `402` — Insurance comparable-pool requires a paid analyst plan (caller's tier is not `pro`, `admin`, `supply_chain_risk`, or `professional`)
* `400` — Invalid IMO number - must be exactly 7 digits.
* `404` — Vessel not found.
* `500` — Internal server error

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/insurance/comparable-pool?imo=9622629&limit=50"
```

## `GET` `/api/v1/insurance/premium-adjustment` [#get-apiv1insurancepremium-adjustment]


  Requires API key with analyst access.


Calculate a premium adjustment factor for a vessel. The factor is based on the vessel's risk score, sanctions exposure, PSC inspection history, and dark fleet activity. A factor above 1.0 suggests a premium increase; below 1.0 suggests a discount.

**Parameters**

| Name  | Type   | Required | Description        |
| ----- | ------ | -------- | ------------------ |
| `imo` | string | ✓        | 7-digit IMO number |

**Response**

```json
{
  "imo_number": "9622629",
  "vessel_name": "MV Meridian",
  "generated_at": "2026-07-23T00:00:00.000Z",
  "premium_adjustment": {
    "mappingVersion": "2026-04-v1",
    "factor": 1.15,
    "baseFactor": 1.0,
    "additiveAdjustments": {
      "risk_score": 0.02,
      "sanctions_matches": 0,
      "detained_inspections_12m": 0,
      "deficiencies_per_inspection_12m": 0.01,
      "dark_events_90d": 0.01,
      "vessel_age": 0.02
    }
  },
  "underwriting_features": {
    "risk_score": 42,
    "risk_tier": "medium",
    "sanctions_matches": 0,
    "detained_inspections_12m": 0,
    "deficiencies_per_inspection_12m": 3,
    "dark_events_90d": 1,
    "vessel_age_years": 14
  }
}
```

Top-level fields are `imo_number`, `vessel_name`, `generated_at`, `premium_adjustment`, `underwriting_features`. `premium_adjustment` carries `mappingVersion`, `factor`, `baseFactor`, `additiveAdjustments` (camelCase, unlike the rest of the response).

**Errors**

* `402` — Insurance underwriting requires a paid analyst plan (caller's tier is not `pro`, `admin`, `supply_chain_risk`, or `professional`)
* `400` — Invalid IMO number - must be exactly 7 digits.
* `404` — Vessel not found.
* `500` — Internal server error

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/insurance/premium-adjustment?imo=9622629"
```

## `GET` `/api/v1/insurance/methodology` [#get-apiv1insurancemethodology]


  Requires API key.


Returns documentation on how claims probabilities and premium adjustment factors are computed, including the input features, model type, and validation approach. Unlike the other `insurance/*` endpoints, this one is not tier-gated — any valid API key can call it.

**Response**

```json
{
  "generated_at": "2026-07-23T00:00:00.000Z",
  "submission_profile": "marine-insurance-regulatory-support",
  "versions": {
    "premium_mapping": "2026-04-v1",
    "claims_model": "claims-proxy-2026-04-v1",
    "comparable_pool": "cohort-window-2026-04-v1"
  },
  "methodology": {
    "premium_adjustment": {
      "description": "Versioned actuarial mapping from risk tier and safety signals to premium adjustment factor.",
      "equation": "factor = base(tier) + risk_score + sanctions + detention + deficiencies + dark_events + vessel_age",
      "clamped_range": [0.6, 2.5]
    },
    "comparable_pool": {
      "description": "Peer cohort selected by vessel class, age window, and DWT band for underwriter benchmarking.",
      "cohort_windows": { "age_years": "+/- 5 years", "dwt": "70%-130%" }
    },
    "claims_prediction": {
      "description": "Claims probability model calibrated from PSC inspection history using detention/deficiency incident proxy.",
      "incident_proxy": "detained=true OR deficiencies_found>=10",
      "smoothing": "Laplace smoothing ((incidents+1)/(observations+2))"
    }
  },
  "audit_trail": {
    "controls": [
      "Every actuarial endpoint call writes audit_log entries with user/api key metadata.",
      "Version identifiers are returned in every response for reproducibility.",
      "Input features and cohort sizes are returned to support regulator replay."
    ],
    "relevant_endpoints": [
      "/api/v1/insurance/premium-adjustment?imo=IMO",
      "/api/v1/insurance/comparable-pool?imo=IMO",
      "/api/v1/insurance/claims-prediction?imo=IMO"
    ]
  }
}
```

**Example**

```bash
curl https://www.axiomoverwatch.io/api/v1/insurance/methodology
```


# Investigations (/overwatch/api/investigations)



Build investigation dossiers on any vessel by pulling together all risk signals, dark events, STS transfers, destination deceptions, and PSC inspections into a single case file. Analysts can annotate signals with feedback, export case files for compliance, and see step-by-step explanations of how each detection was made.

## Case files [#case-files]

Case-file retrieval and analyst annotation — `GET` and `PATCH` `/api/v1/vessels/{imo}/case-files` — are documented on the dedicated [Case Files page](/overwatch/api/case-files), including the full evidence-kind reference. The endpoints below cover compliance export and trade-intelligence reconciliation.

### `GET` `/api/v1/vessels/{imo}/case-files/export` [#get-apiv1vesselsimocase-filesexport]


  Requires an API key whose tier is 

  `internal`

   or 

  `admin`

   — other tiers get 

  `403 Admin API key required.`


Export a case file as a compliance-ready bundle: a markdown case narrative, the full source-data snapshot (vessel, motifs, dark events, STS events, sanctions matches, chain of custody), a gray-fleet attribution score, a trade-flow reconciliation slice, a FedRAMP-Moderate readiness checklist, and a SHA-256 manifest over the bundled files.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

There is no `case_id` parameter — the handler doesn't read query params at all. It always returns one aggregated bundle built from the vessel's current signals; there's no per-case selection.

**Response**

```json
{
  "package_type": "government_case_file_bundle",
  "generated_at": "2026-04-15T10:00:00Z",
  "imo_number": "9622629",
  "pdf_document": {},
  "source_data_bundle": {},
  "sha256_manifest": [],
  "upstream_source_urls": [],
  "methodology_notes": [],
  "chain_of_custody": []
}
```

`pdf_document` holds `filename` and a markdown `content_markdown` narrative. `source_data_bundle.data` nests `gray_fleet_report` (`score`, `likely_gray_fleet`, `factors`, `rationale`), `trade_flow_reconciliation` (`selection_mode`, `rows`), and `fedramp_moderate_readiness` (`profile`, `checks`). `sha256_manifest` entries carry `path`, `sha256`, `bytes`. `chain_of_custody` entries carry `case_id`, `motif_alert_id`, `detected_at`, `acknowledged`, `analyst_annotation_updated_at`, `exported_at`.

**Errors**

* `400` — IMO isn't exactly 7 digits
* `403` — API key tier isn't `internal` or `admin`
* `500` — vessel or motif-alert lookup failed

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9622629/case-files/export
```

### `GET` `/api/v1/vessels/{imo}/case-files/reconciliation` [#get-apiv1vesselsimocase-filesreconciliation]


  Not launch-supported. The handler is a stub that always returns 

  `503`

   — it doesn't check authentication, the 

  `imo`

   path segment, or any query params.


Cross-reference a vessel's investigation data against supply chain entity records, trade mirror discrepancies, and sanctions matches. Use this to reconcile risk signals with trade intelligence.

**This endpoint currently always returns `503`:**

```json
{
  "error": "Investigation case-file reconciliation is not launch-supported",
  "code": "feature_unavailable"
}
```

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9622629/case-files/reconciliation
```

***

## Signal feedback [#signal-feedback]

Signal listing, adjudication, and repeat-alert suppression — `GET` and `PATCH` `/api/v1/vessels/{imo}/signal-feedback` — plus the org-wide `GET /api/v1/signals/feedback-calibration` roll-up are documented on the dedicated [Signals page](/overwatch/api/signals).

***

## Signal explainability [#signal-explainability]

Explainability breakdowns — `GET /api/v1/signals/explainability` — are documented on the dedicated [Signals page](/overwatch/api/signals). The endpoint takes an optional `imo` and returns spoofing, cargo, and motif explanations in a single response.

***

## Risk methodology [#risk-methodology]


  Requires API key.


### `GET` `/api/v1/vessels/{imo}/risk-methodology` [#get-apiv1vesselsimorisk-methodology]

Returns the full 14-factor risk score breakdown for a vessel, showing each factor's raw value, weight, and weighted contribution to the overall score. Also computes a 90-day trend per factor and a single-factor counterfactual ("what if this factor were X"). Defaults to a PDF report; pass `format=json` for the structured breakdown.

**Parameters**

| Name     | Type   | Required | Description                                                                                                                                                                               |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `imo`    | string | ✓        | 7-digit IMO number (path param)                                                                                                                                                           |
| `format` | string |          | `pdf` (default) or `json`                                                                                                                                                                 |
| `factor` | string |          | Which risk factor to use in the counterfactual scenario (e.g. `gap_duration`). Defaults to the top-ranked contributing factor if omitted or not found among the vessel's current factors. |
| `raw`    | number |          | Hypothetical raw value (0–100) for `factor`, used to project a counterfactual score. Defaults to 50; clamped to 0–100.                                                                    |

**Risk factors**

| Factor                  | Weight | Description                                            |
| ----------------------- | ------ | ------------------------------------------------------ |
| `gap_duration`          | 9%     | Duration of AIS coverage gaps                          |
| `gap_frequency`         | 9%     | Number of gaps in the last 90 days                     |
| `location_risk`         | 9%     | Whether gaps occur in high-risk zones                  |
| `flag_state`            | 9%     | Flag of convenience or sanctioned registry             |
| `vessel_age`            | 5%     | Years since build                                      |
| `vessel_type`           | 2.5%   | Risk profile by vessel category                        |
| `prior_history`         | 5%     | Historical risk events                                 |
| `sanctions_match`       | 9%     | Ownership-based sanctions screening                    |
| `sts_involvement`       | 7.5%   | Ship-to-ship transfer activity                         |
| `draft_anomaly`         | 7.5%   | Unexplained draft changes                              |
| `loitering`             | 7.5%   | Time spent stationary or slow-rolling in unusual zones |
| `identity_manipulation` | 7.5%   | Flag, name, or MMSI changes                            |
| `pi_coverage`           | 7.5%   | Whether the vessel has P\&I club coverage              |
| `obfuscation_risk`      | 5%     | Composite deceptive behavior score                     |

**Response** (`format=json`)

```json
{
  "vessel": {
    "imo_number": "9622629",
    "name": "",
    "score": 0,
    "tier": ""
  },
  "contributions": [],
  "trend_90d": [],
  "counterfactual": {
    "factor": null,
    "input_raw": 50,
    "projected_score": 0,
    "projected_tier": ""
  },
  "methodology": {
    "model": "XGBoost risk model (14-feature weighted contribution view)",
    "source": "dark_events.risk_factors"
  }
}
```

Each `contributions` entry carries `factor`, `weight`, `raw_value`, `weighted_score`. Each `trend_90d` entry carries `factor`, `avg`, `delta`. `format=pdf` (the default) instead returns an `application/pdf` binary attachment, not this JSON body.

**Errors**

* `400` — IMO isn't exactly 7 digits
* `404` — vessel not found
* `500` — dark-events lookup failed

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9622629/risk-methodology
```

```bash
# Download a PDF risk report
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/vessels/9622629/risk-methodology?format=pdf" \
  -o risk-report.pdf
```


# LNG (/overwatch/api/lng)



LNG carrier tracking across 5 terminals.

## `GET` `/api/v1/lng` [#get-apiv1lng]


  Requires API key.


LNG dashboard: carriers at terminals, 7-day volume estimates, departures.

**Response**

```json
{
  "carriers_at_terminals": 0,
  "estimated_volume_7d_tons": 0,
  "departures_7d": 0,
  "active_terminals": 0,
  "total_terminals": 0,
  "terminals": [],
  "tier": "pro"
}
```

`terminals` is the list of monitored LNG terminal slugs (`ras-laffan`, `gorgon`, `yamal`, `corpus-christi-lng`, `freeport-lng`).

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/lng
```

## `GET` `/api/v1/lng/terminals` [#get-apiv1lngterminals]


  Requires API key.


List all LNG terminals.

**Response**

```json
{
  "terminals": [],
  "tier": "pro"
}
```

Each `terminals` entry carries `slug`, `name`, `country`, `region`, `carriers_in_port`, `departures_7d`, `estimated_volume_7d_tons`.

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/lng/terminals
```


# Market Data (/overwatch/api/market-data)



Commodity prices, USDA transport data, and seasonal anomalies.

## `GET` `/api/v1/commodity-prices` [#get-apiv1commodity-prices]

IMF commodity benchmark prices, sourced via the [FRED](https://fred.stlouisfed.org/) API. Series cover wheat, corn, soybeans, crude oil (Brent and WTI), coal, US natural gas, and iron ore. Refreshed weekly on Monday at 06:00 UTC.

**Parameters**

| Name        | Type   | Required | Description                                                                                                     |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `commodity` | string |          | e.g. 'wheat', 'crude\_oil\_brent', 'iron\_ore'                                                                  |
| `since`     | string |          | ISO date                                                                                                        |
| `cursor`    | string |          | Pagination cursor — pass the previous response's `pagination.next_cursor`                                       |
| `limit`     | number |          | Default 100. Clamped to your tier's per-call ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin) |

**Response**

```json
{
  "commodity_prices": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `commodity_prices` entry carries `id`, `commodity`, `price_date`, `price_usd`, `unit`, `source`, `fetched_at`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/commodity-prices?commodity=VALUE&since=VALUE
```

## `GET` `/api/v1/transport-data` [#get-apiv1transport-data]

USDA Grain Transportation Report data: barge, rail, and truck volumes.

**Parameters**

| Name        | Type   | Required | Description                                                                                                     |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `mode`      | string |          | 'barge' \| 'rail' \| 'truck'                                                                                    |
| `commodity` | string |          | Commodity filter                                                                                                |
| `region`    | string |          | Origin region (fuzzy match)                                                                                     |
| `since`     | string |          | ISO date                                                                                                        |
| `cursor`    | number |          | Offset cursor — pass the previous response's `pagination.next_cursor`                                           |
| `limit`     | number |          | Default 100. Clamped to your tier's per-call ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin) |

**Response**

```json
{
  "transport_data": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `transport_data` entry carries `id`, `report_week`, `region`, `commodity`, `transport_mode`, `volume_tons`, `volume_bushels`, `yoy_change_pct`, `source_url`, `fetched_at`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/transport-data?mode=VALUE&commodity=VALUE
```

## `GET` `/api/v1/anomalies` [#get-apiv1anomalies]

Seasonal and trailing anomalies in export volumes.

**Parameters**

| Name       | Type   | Required | Description                                                                                                     |
| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `port`     | string | Yes      | Port ID                                                                                                         |
| `type`     | string |          | 'trailing' \| 'yoy' \| 'seasonal\_avg' \| 'seasonal\_range'                                                     |
| `severity` | string |          | 'moderate' \| 'high' \| 'critical'                                                                              |
| `cursor`   | string |          | Pagination cursor — pass the previous response's `pagination.next_cursor`                                       |
| `limit`    | number |          | Default 100. Clamped to your tier's per-call ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin) |

**Response**

```json
{
  "anomalies": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `anomalies` entry returns the full `anomaly_events` row, plus an embedded `ports` object with `id`, `slug`, `name`, `country`.

**Error responses**

| Status | When              |
| ------ | ----------------- |
| `400`  | `port` is missing |
| `500`  | Query failed      |

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/anomalies?port=VALUE&type=VALUE
```

## `GET` `/api/v1/anomalies/maturity` [#get-apiv1anomaliesmaturity]

Seasonal analysis maturity levels per port (data sufficiency).

**Response**

```json
{
  "maturity": [],
  "tier": "pro"
}
```

Each `maturity` entry returns the full `port_seasonal_maturity` row, plus an embedded `ports` object with `id`, `slug`, `name`, `country`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/anomalies/maturity
```

## `GET` `/api/v1/calibration` [#get-apiv1calibration]

Volume estimation calibration data (per-vessel-type and self-calibrated).

**Response**

```json
{
  "calibration": {},
  "overrides": [],
  "self_calibrated": [],
  "manual_overrides": [],
  "tier": "pro"
}
```

`calibration` is the merged vessel-type coefficient map (hardcoded defaults overlaid with DB overrides). `overrides` is the full, unfiltered list of `vessel_type_calibration` rows (`select('*')`); `self_calibrated` and `manual_overrides` are that same list split by `source`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/calibration
```

## `POST` `/api/v1/calibration` [#post-apiv1calibration]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Set a manual calibration override for a vessel type, optionally scoped to a single port.

This **replaces** rather than accumulates: any existing row for the same
`vessel_type` + `port_id` pair is deleted before the new one is inserted, so a
repeated call is idempotent and there is never more than one manual override per
pair. Omitting `port_id` targets the global (null-port) override specifically —
it does not clear per-port overrides. The stored row is always written with
`source: "manual"` and a server-side `computed_at`, so a manual override is
distinguishable from a self-calibrated one in the `GET` response.

**Parameters** (JSON body)

| Name             | Type   | Required | Description                                                       |
| ---------------- | ------ | -------- | ----------------------------------------------------------------- |
| `vessel_type`    | string | Yes      | Vessel type identifier                                            |
| `port_id`        | string |          | Scope the override to a specific port; omit for a global override |
| `tons_per_meter` | number | Yes      | Calibration coefficient                                           |
| `variance_pct`   | number | Yes      | Variance percentage                                               |
| `confidence`     | string | Yes      | 'high' \| 'medium' \| 'low'                                       |

**Response**

```json
{ "calibration": {} }
```

Returns the full inserted `vessel_type_calibration` row (status `201`).

**Error responses**

| Status | When                                                                                                                   |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing `vessel_type`, `tons_per_meter`, `variance_pct`, or `confidence`; or `confidence` is not `high`/`medium`/`low` |
| `500`  | Insert failed                                                                                                          |

See [admin authorization](/overwatch/api/admin-auth) for the `401`/`403`/`429` failure modes shared by all admin-gated endpoints.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/calibration \
  -d '{"vessel_type":"bulk_carrier","tons_per_meter":1200,"variance_pct":5,"confidence":"high"}'
```


# Mining (/overwatch/api/mining)



Mining terminal tracking: iron ore and coal across 4 terminals.

## `GET` `/api/v1/mining` [#get-apiv1mining]


  Requires API key.


Mining dashboard: carriers, volumes, coal vs iron ore departures.

**Response**

```json
{
  "carriers_at_terminals": 0,
  "estimated_volume_7d_tons": 0,
  "departures_7d": 0,
  "coal_departures_7d": 0,
  "iron_ore_departures_7d": 0,
  "active_terminals": 0,
  "total_terminals": 0,
  "terminals": [],
  "tier": "pro"
}
```

`terminals` is the list of monitored mining terminal slugs (`newcastle-coal`, `richards-bay`, `gladstone`, `saldanha-bay`).

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/mining
```

## `GET` `/api/v1/mining/terminals` [#get-apiv1miningterminals]


  Requires API key.


List all mining terminals.

**Response**

```json
{
  "terminals": [],
  "tier": "pro"
}
```

Each `terminals` entry carries `slug`, `name`, `country`, `region`, `commodity`, `carriers_in_port`, `departures_7d`, `estimated_volume_7d_tons`. `commodity` is `coal` for `newcastle-coal`/`richards-bay`/`gladstone` and `iron_ore` for `saldanha-bay`.

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/mining/terminals
```


# API overview (/overwatch/api/overview)



The Axiom Overwatch API exposes 70+ endpoints across vessel tracking, risk intelligence, commodity flows, satellite imagery, P\&I coverage, trade flows, and more.

## Base URL [#base-url]

```text
https://www.axiomoverwatch.io/api/v1
```

Use the `www` host in API clients. The apex host redirects to it, which is inconvenient for command-line clients that do not follow redirects automatically.

## Authentication [#authentication]

Most endpoints — including `/api/v1/positions`, `/api/v1/vessels`, and the rest of the read surface — require an API key. Only a small slice is unauthenticated: `/api/v1/health`, `/api/v1/ports`, `/api/v1/billing/plans`, `/api/v1/positions/latest`, and the single-vessel latest-position lookup below. Mutating endpoints, high-volume reads, and analyst/admin-only operations require a key on top of that, and several require a paid tier specifically.

A small public-tier slice — the [single-vessel latest-position lookup](/overwatch/api/vessels#get-apiv1aisproviderimolocationlatest) — is fully open, requires no key, ships JSON-LD attribution, and has its own [OpenAPI 3.1 spec](https://www.axiomoverwatch.io/openapi/positions.yaml) suitable for citation by journalists, academics, and AI ingestion pipelines.

Pass the key via the `X-API-Key` header:

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/positions?port=houston
```

Generate keys in **Settings → API Keys** in the Overwatch dashboard.

## Access tiers [#access-tiers]

| Plan                  | Rate limit                                                                | History depth | Features                                                        |
| --------------------- | ------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------- |
| **Free**              | 50 req/day                                                                | 7 days        | Public endpoints, ports, basic positions (max 20 rows/call)     |
| **Starter**           | 1,000 req/day                                                             | 90 days       | All read endpoints, CSV exports (max 100 rows/call)             |
| **Pro**               | 10,000 req/day                                                            | 365 days      | All endpoints, webhooks, priority sync (max 500 rows/call)      |
| **Supply Chain Risk** | 10,000 req/day (same technical ceiling as Pro under the current tier map) | 365 days      | Pro + dark fleet alerts, custom risk scoring, dedicated support |

All tiers also share a flat 60 requests/minute per-IP throttle applied to every `/api/*` request before your key is checked — see [Rate limiting](#rate-limiting).

See `/api/v1/billing/plans` for live pricing.

## Rate limiting [#rate-limiting]

Two independent limits apply, and neither adds `X-RateLimit-*` headers to successful responses:

* **Per-IP throttle** — a flat 60 requests/minute cap on every `/api/*` request, enforced before your API key is checked. Exceeding it returns `429` with `{ "error": "Rate limit exceeded" }` and a `Retry-After: 60` header.
* **Per-key daily quota** — each API key's tier has a fixed requests-per-day ceiling (see [Access tiers](#access-tiers)). Exceeding it returns `429` with `{ "error": "Daily rate limit exceeded", "limit": , "tier": "", "upgrade": "..." }` — no `Retry-After` header on this one.

## Response format [#response-format]

JSON is the default response format, with data nested under a top-level key matching the resource (e.g. `vessels`, `positions`, `events`). Endpoints that support a `format` parameter may instead return CSV or PDF. Most errors return just:

```json
{ "error": "human-readable message" }
```

A minority of endpoints — mainly features that aren't launch-supported yet — add a machine-readable `code` field alongside `error`.

## Methodology [#methodology]

Every endpoint that returns inferred or modeled data (cargo estimates, risk scores, dark fleet detections, draft anomalies) includes:

* A `confidence` or `tier` field indicating signal strength
* A `methodology` link in the response or in the endpoint docs

For modeling specifics, see the [Methodology](/overwatch/methodology/cargo-validation) section.

## Port slugs [#port-slugs]

Ports are referenced by slug (e.g. `houston`, `santos`, `singapore`, `rotterdam`). Get the full list from `GET /api/v1/ports`.

## Quick start [#quick-start]


  
    
      cURL
    

    
      Python
    

    
      Node.js
    
  

  
    ```bash
    # 1. List monitored ports
    curl https://www.axiomoverwatch.io/api/v1/ports

    # 2. Get vessel positions at a port (API key required)
    curl -H "X-API-Key: YOUR_KEY" \
      https://www.axiomoverwatch.io/api/v1/positions?port=houston

    # 3. Pull risk-scored vessels (auth required for full data)
    curl -H "X-API-Key: YOUR_KEY" \
      https://www.axiomoverwatch.io/api/v1/risk/vessels?tier=critical
    ```
  

  
    ```python
    import requests

    API = "https://www.axiomoverwatch.io/api/v1"
    headers = {"X-API-Key": "YOUR_KEY"}

    # 1. List monitored ports
    ports = requests.get(f"{API}/ports").json()

    # 2. Get vessel positions at a port (API key required)
    positions = requests.get(
        f"{API}/positions", params={"port": "houston"}, headers=headers
    ).json()

    # 3. Pull risk-scored vessels (auth required for full data)
    risky = requests.get(
        f"{API}/risk/vessels", params={"tier": "critical"}, headers=headers
    ).json()
    ```
  

  
    ```js
    const API = "https://www.axiomoverwatch.io/api/v1";
    const headers = { "X-API-Key": "YOUR_KEY" };

    // 1. List monitored ports
    const ports = await fetch(`${API}/ports`).then((r) => r.json());

    // 2. Get vessel positions at a port (API key required)
    const positions = await fetch(`${API}/positions?port=houston`, { headers }).then(
      (r) => r.json()
    );

    // 3. Pull risk-scored vessels (auth required for full data)
    const risky = await fetch(`${API}/risk/vessels?tier=critical`, { headers }).then(
      (r) => r.json()
    );
    ```
  


## SDK + MCP [#sdk--mcp]

* **Python**: `pip install axiom-overwatch` — see [SDKs & MCP](/overwatch/api/sdk).
* **MCP server**: lets Claude / GPT / any MCP-compatible AI agent query Overwatch directly.

## Where to from here [#where-to-from-here]

Browse the endpoints by category in the sidebar, or jump to the most-used groups:


  
    Real-time AIS positions and vessel registry
  

  
    Dark fleet, STS, loitering, identity changes
  

  
    Bilateral commodity trade, mirror discrepancies, sanctions
  

  
    CSRD/SEC Scope 3 maritime emissions reports
  



# P&I Coverage (/overwatch/api/pi)



Protection & Indemnity club coverage for vessels.

## `GET` `/api/v1/pi-clubs` [#get-apiv1pi-clubs]

List all P\&I clubs with risk tier and IG membership.

**Response**

```json
{
  "clubs": [],
  "tier": "pro"
}
```

Each `clubs` entry carries `id`, `name`, `short_name`, `risk_tier`, `is_ig_member`, `country`.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/pi-clubs
```

## `GET` `/api/v1/pi-coverage` [#get-apiv1pi-coverage]

P\&I coverage records for vessels.

**Parameters**

| Name     | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `vessel` | string |          | IMO number  |

**Response**

```json
{
  "coverage": [],
  "tier": "pro"
}
```

Each `coverage` entry returns the full `vessel_pi_coverage` row, plus a nested `pi_clubs` object with `id`, `name`, `short_name`, `risk_tier`, `is_ig_member`, `country`.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/pi-coverage?vessel=VALUE
```

## `POST` `/api/v1/pi-coverage/import` [#post-apiv1pi-coverageimport]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Bulk import P\&I coverage from CSV.

**Parameters**

Request body is raw CSV text (not JSON), one row per vessel. A header row is optional — it's detected and skipped automatically when the first line contains `imo`.

| Column         | Type   | Required | Description                                                                                  |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `imo_number`   | string | ✓        | 5–8 digit IMO number. Rows without a valid `imo_number` are silently skipped.                |
| `pi_club`      | string |          | Club name, fuzzy-matched (case-insensitive substring) against `pi_clubs.name` / `short_name` |
| `status`       | string |          | `current` \| `expired`; anything else (including blank) becomes `unknown`                    |
| `policy_start` | string |          | ISO `YYYY-MM-DD` date; a malformed date rejects the row (reported in `invalid_dates`)        |
| `policy_end`   | string |          | ISO `YYYY-MM-DD` date; a malformed date rejects the row (reported in `invalid_dates`)        |

**Response**

```json
{
  "rows_processed": 0,
  "matched": 0,
  "unmatched_clubs": [],
  "invalid_dates": []
}
```

**Errors**

* `400` — request body is empty
* `400` — no valid rows found in the CSV (still returns `rows_processed`, `matched`, `unmatched_clubs`, `invalid_dates`)
* `500` — failed to load the P\&I club directory
* `500` — upsert failed

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/pi-coverage/import \
  --data-binary $'imo_number,pi_club,status,policy_start,policy_end\n9074729,North of England,current,2026-01-01,2027-01-01'
```


# Ports (/overwatch/api/ports)



List monitored ports and query port events across all verticals.

## `GET` `/api/v1/ports` [#get-apiv1ports]


  No API key required — this endpoint is public.


List all monitored ports with slug, name, country, and region.

**Parameters**

| Name     | Type   | Required | Description                                                                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string |          | Pagination cursor — pass the `slug` of the last port from the previous page to fetch the next page.                                                 |
| `limit`  | number |          | Results per page. Default `50`, clamped to at most `20` — this endpoint always runs at the public tier ceiling, regardless of any API key supplied. |

**Response**

```json
{
  "ports": [],
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  },
  "tier": "public"
}
```

Each `ports` entry carries `id`, `slug`, `name`, `country`, `region`.

**Errors**

* `500` — The ports query failed.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/ports
```

## `POST` `/api/v1/ports/batch` [#post-apiv1portsbatch]


  Requires API key.


Batch lookup of ports by slug.

**Parameters**

| Name    | Type      | Required | Description                                                                                 |
| ------- | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `slugs` | string\[] | ✓        | Non-empty array of port slugs to look up. Capped per tier — free: 5, starter/pro/admin: 20. |

**Response**

```json
{
  "ports": [],
  "requested": 0,
  "processed": 0,
  "tier": "pro"
}
```

Each `ports` entry carries `id`, `slug`, `name`, `country`, `region`. `requested` is the number of slugs sent; `processed` is the number actually queried after the per-tier cap.

**Errors**

* `400` — `slugs` was missing, not an array, or contained no non-empty strings.

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/ports/batch \
  -d '{ "slugs": ["rotterdam", "singapore"] }'
```

## Port events [#port-events]

Port events represent arrivals, departures, berth assignments, and other vessel activity recorded at monitored ports. Each port event carries the full [APRS envelope](/locus/data-standards) plus these domain-specific fields:

| Field       | Type   | Description                                                                                                                                 |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `mmsi`      | `text` | 9-digit Maritime Mobile Service Identity of the vessel. Use this to join port events to vessel records or cross-reference identity changes. |
| `h3_index`  | `text` | H3 cell at resolution 8 for the event location.                                                                                             |
| `record_id` | `text` | Stable APRS URN for deduplication and audit trails.                                                                                         |

You can query port events through the `codex_compliance_summary` view to verify envelope coverage, or join them directly to vessel data using `mmsi`:

```sql
-- Port events for a vessel, joined to the vessel registry
select pe.*, v.name, v.flag, v.vessel_type
from port_events pe
join vessels v on v.mmsi = pe.mmsi
where pe.mmsi = '211331640'
order by pe.occurred_at desc;
```


  The `mmsi` column is indexed with a partial index on non-null values, so vessel-scoped queries against `port_events` are efficient even on large datasets.


## `GET` `/api/v1/health` [#get-apiv1health]


  No API key required — this endpoint is public.


System health check. Returns position counts and ingestion status.

**Response**

```json
{
  "status": "healthy",
  "platform": {
    "positions": 0,
    "vessels": 0,
    "ports": 0,
    "positions_last_hour": 0
  },
  "intelligence": {
    "sanctions_entities": 0,
    "trade_flow_records": 0,
    "dark_events": 0,
    "pi_coverage": 0,
    "disruption_signals": 0,
    "active_alerts": 0
  },
  "data_sources": 17,
  "api_endpoints": 65,
  "mcp_tools": 0
}
```

`status` is `healthy` when at least one AIS position was ingested in the last hour, else `degraded`. `platform` carries `positions`, `vessels`, `ports`, `positions_last_hour`. `intelligence` carries `sanctions_entities`, `trade_flow_records`, `dark_events`, `pi_coverage`, `disruption_signals`, `active_alerts`. `data_sources`, `api_endpoints`, and `mcp_tools` are fixed platform-level counts.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/health
```


# Risk Intelligence (/overwatch/api/risk)



14-factor risk scoring, dark fleet detection, STS transfers, loitering, identity changes, and draft anomalies.

## Risk tiers [#risk-tiers]

Every dark event is scored 0–100 across 14 weighted factors (gap duration, gap frequency, location proximity to STS hotspots, flag state, vessel age, vessel type, prior history, sanctions match, STS involvement, draft anomaly, loitering, identity manipulation, P\&I coverage, and obfuscation). The numeric score is then bucketed into a `risk_tier` for filtering and alerting.

| Tier       | Score range | Approximate population share   |
| ---------- | ----------- | ------------------------------ |
| `low`      | 0 – 15      | \~p65 — most isolated AIS gaps |
| `medium`   | 16 – 25     | \~p65–p93                      |
| `high`     | 26 – 35     | \~p93–p99.5                    |
| `critical` | 36 – 100    | top \~0.5%                     |

These thresholds are calibrated against the real production score distribution, where most dark events are isolated AIS gaps with zero contribution from compounding factors like sanctions matches or STS involvement. Use `risk_tier=high,critical` to focus on the small subset of events that warrant active investigation, and use `risk_score` directly when you need finer-grained filtering than the tier boundaries provide.

The tier value is stamped on every event returned by `/api/v1/risk/events`, `/api/v1/risk/vessels`, and the `dark_event` webhook payload — see the [Webhooks API](/overwatch/api/webhooks) for the webhook envelope and [Watchlist API](/overwatch/api/watchlist) for tier-aware notification rules.

## `GET` `/api/v1/risk/vessels` [#get-apiv1riskvessels]

All risk-scored vessels. Filter by tier, type, or flag.

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `tier`   | string |          | 'critical' \| 'high' \| 'medium' \| 'low'                                                             |
| `type`   | string |          | Vessel type                                                                                           |
| `flag`   | string |          | Flag state code                                                                                       |
| `cursor` | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`  | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "vessels": [],
  "tier": "pro",
  "source": "vessels",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `vessels` entry carries `imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `dwt`, `risk_score`, `risk_tier`, `risk_updated_at`.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/vessels?tier=VALUE&type=VALUE
```

## `GET` `/api/v1/risk/vessel/{imo}` [#get-apiv1riskvesselimo]

Full risk profile for a single vessel including dark events.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

**Response**

```json
{
  "vessel": {},
  "dark_events": [],
  "events_error": null,
  "tier": "pro"
}
```

`vessel` carries `imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `dwt`, `max_draft`, `risk_score`, `risk_tier`, `risk_updated_at`. Each `dark_events` entry returns the full `dark_events` row plus a computed `explanation` field.

**Errors**

* `400` — Invalid IMO number (must be exactly 7 digits)
* `404` — Vessel not found

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/vessel/9622629
```

## `GET` `/api/v1/risk/events` [#get-apiv1riskevents]

Dark fleet AIS gap events. Filter by tier or vessel.

**Parameters**

| Name      | Type   | Required | Description                                                                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `tier`    | string |          | Risk tier filter                                                                                                |
| `vessel`  | string |          | IMO number                                                                                                      |
| `ongoing` | string |          | 'true' for active gaps only                                                                                     |
| `cursor`  | string |          | Opaque pagination cursor — pass the `next_cursor` value from a previous page (a `gap_start` timestamp boundary) |
| `limit`   | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000.           |

**Response**

```json
{
  "events": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `events` entry returns the full `dark_events` row plus a nested `vessels` object (`imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `risk_tier`) and a computed `explanation` field.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/events?tier=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/stats` [#get-apiv1riskstats]

Aggregate risk statistics: active gaps, critical vessels, hotspots, events by tier.

**Response**

```json
{
  "active_gaps": 12,
  "critical_vessels": 4,
  "active_hotspots": 7,
  "new_events_24h": 18,
  "events_by_tier": {
    "low": 8,
    "medium": 5,
    "high": 3,
    "critical": 2
  },
  "tier": "pro"
}
```

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/stats
```

## `GET` `/api/v1/risk/sts` [#get-apiv1risksts]

Ship-to-ship transfer events with confidence and draft transfer data.

**Parameters**

| Name         | Type   | Required | Description                                                                                           |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `confidence` | string |          | 'suspected' \| 'confirmed' \| 'verified'                                                              |
| `vessel`     | string |          | IMO number (checks both vessels)                                                                      |
| `method`     | string |          | Detection method                                                                                      |
| `cursor`     | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`      | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "events": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `events` entry returns the full `sts_events` row plus nested `vessel_a` and `vessel_b` objects (`imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `risk_tier`).

**Errors**

* `400` — Invalid IMO number (when `vessel` fails the 7-digit check)

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/sts?confidence=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/sts/stats` [#get-apiv1riskstsstats]

STS aggregate statistics: total events, by confidence, tonnage, active encounters.

**Response**

```json
{
  "total_events": 128,
  "by_confidence": {
    "suspected": 74,
    "confirmed": 39,
    "verified": 15
  },
  "total_tonnage": 1250000,
  "active_encounters": 6,
  "tier": "pro"
}
```

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/sts/stats
```

## `GET` `/api/v1/risk/loitering` [#get-apiv1riskloitering]

Loitering events (stationary or slow-roll) with context zones.

**Parameters**

| Name      | Type   | Required | Description                                                                                           |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `type`    | string |          | 'stationary' \| 'slow\_roll'                                                                          |
| `vessel`  | string |          | IMO number                                                                                            |
| `context` | string |          | Context zone                                                                                          |
| `cursor`  | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`   | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "events": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `events` entry returns the full `loitering_events` row plus a nested `vessels` object (`imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `risk_tier`).

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/loitering?type=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/identity` [#get-apiv1riskidentity]

Vessel identity change events (flag, name, MMSI).

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `field`  | string |          | 'flag' \| 'name' \| 'mmsi'                                                                            |
| `vessel` | string |          | IMO number                                                                                            |
| `cursor` | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`  | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "events": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `events` entry returns the full `identity_change_events` row plus a nested `vessels` object (`imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `risk_tier`).

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/identity?field=VALUE&vessel=VALUE
```

## `GET` `/api/v1/risk/identity/history` [#get-apiv1riskidentityhistory]

Full identity history for a vessel.

**Parameters**

| Name     | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `vessel` | string | ✓        | IMO number  |

**Response**

```json
{
  "history": [],
  "tier": "pro"
}
```

Each `history` entry returns the full `vessel_identity_history` row.

**Errors**

* `400` — Missing required parameter: vessel (IMO number)

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/identity/history?vessel=VALUE
```

## `GET` `/api/v1/risk/mismatches` [#get-apiv1riskmismatches]

Draft mismatch events: directional, magnitude, or zero-change anomalies.

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `type`   | string |          | 'directional' \| 'magnitude' \| 'zero\_change'                                                        |
| `vessel` | string |          | IMO number                                                                                            |
| `port`   | string | ✓        | Port ID (UUID)                                                                                        |
| `cursor` | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`  | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "events": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `events` entry returns the full `draft_mismatch_events` row plus nested `vessels` (`imo_number`, `mmsi`, `name`, `vessel_type`, `flag`, `risk_tier`) and `ports` (`id`, `name`, `country`, `slug`) objects.

**Errors**

* `400` — port is required (when `port` is omitted)

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/mismatches?type=VALUE&vessel=VALUE&port=VALUE
```

## `GET` `/api/v1/risk/hotspots` [#get-apiv1riskhotspots]

STS hotspot zones (seeded and auto-discovered).

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `active` | string |          | Default 'true'. Pass 'false' for all.                                                                 |
| `cursor` | number |          | Pagination offset (row index). Default 0.                                                             |
| `limit`  | number |          | Default 200. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "hotspots": [],
  "tier": "pro",
  "pagination": { "limit": 200, "has_more": false, "next_cursor": null }
}
```

Each `hotspots` entry returns the full `sts_hotspots` row.

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/hotspots?active=VALUE&limit=VALUE
```

## `GET` `/api/v1/risk/baselines` [#get-apiv1riskbaselines]

Port-level draft baselines used for anomaly detection.

**Response**

```json
{
  "baselines": [],
  "tier": "pro"
}
```

Each `baselines` entry returns the full `port_draft_baselines` row plus a nested `ports` object (`id`, `name`, `country`, `slug`).

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/risk/baselines
```


# River Levels (/overwatch/api/river-levels)



Real-time USGS gauge data for waterways critical to grain barge transport.

## `GET` `/api/v1/river-levels` [#get-apiv1river-levels]


  Requires API key.


Live river water levels for Mississippi, Ohio, Illinois, Columbia rivers and Houston. Returns level in feet with status alerts (`normal`/`low`/`critical_low`/`high`/`flood`).

**Response**

```json
{
  "readings": [],
  "alerts": [],
  "tier": "pro"
}
```

Each `readings` (and `alerts`) entry carries `site_id`, `name`, `river`, `port`, `level_ft`, `status`, `critical_low_ft`, `flood_stage_ft`, `timestamp`. `alerts` is the subset of `readings` where `status` is not `normal`.

**Errors**

* `502` — Upstream USGS API request failed
* `500` — Internal server error

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/river-levels
```


# Trade Routes (/overwatch/api/routes)



Trade flow analysis, route shifts, and destination deceptions.

## `GET` `/api/v1/routes/flows` [#get-apiv1routesflows]

Trade route flows between ports with tonnage and market share.

**Parameters**

| Name          | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `origin`      | string |          | Origin port ID                                                                                        |
| `port`        | string |          | Origin port slug (alternative to `origin`)                                                            |
| `destination` | string |          | Destination port ID                                                                                   |
| `week`        | string |          | Week start date (ISO)                                                                                 |
| `commodity`   | string |          | Commodity filter                                                                                      |
| `cursor`      | number |          | Pagination offset (default 0)                                                                         |
| `limit`       | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

Either `origin` or `port` is required.

**Response**

```json
{
  "flows": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `flows` entry returns the full `trade_route_flows` row, plus a joined `origin_port` object with `id`, `slug`, `name`, `country`.

**Errors**

* `400` — `origin` or `port` is required
* `404` — Port not found (when `port` doesn't resolve to a known slug)

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/routes/flows?origin=VALUE&destination=VALUE
```

## `GET` `/api/v1/routes/shifts` [#get-apiv1routesshifts]

Detected trade route shifts and deviations.

**Parameters**

| Name          | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `severity`    | string |          | 'moderate' \| 'high' \| 'critical'                                                                    |
| `origin`      | string |          | Origin port ID                                                                                        |
| `destination` | string |          | Destination port ID                                                                                   |
| `commodity`   | string |          | Commodity filter                                                                                      |
| `shift_type`  | string |          | Route shift type filter                                                                               |
| `cursor`      | number |          | Pagination offset (default 0)                                                                         |
| `limit`       | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "shifts": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `shifts` entry returns the full `trade_route_shifts` row, plus a joined `origin_port` object with `id`, `slug`, `name`, `country`.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/routes/shifts?severity=VALUE&origin=VALUE
```

## `GET` `/api/v1/routes/deceptions` [#get-apiv1routesdeceptions]

Vessels whose actual destination didn't match declared destination.

**Parameters**

| Name          | Type   | Required | Description                                                                                           |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `vessel`      | string |          | IMO number                                                                                            |
| `suspicious`  | string |          | 'true' \| 'false'                                                                                     |
| `actual_port` | string |          | Actual port ID                                                                                        |
| `cursor`      | number |          | Pagination offset (default 0)                                                                         |
| `limit`       | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "deceptions": [],
  "tier": "pro",
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `deceptions` entry returns the full `destination_deceptions` row, plus a joined `vessel` object with `imo_number`, `name`, `vessel_type`, `flag`, `risk_score`, `risk_tier`.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/routes/deceptions?vessel=VALUE&suspicious=VALUE
```


# Sanctions screening (/overwatch/api/sanctions)



Overwatch continuously screens vessel ownership chains against OFAC, EU, UN, and OpenSanctions consolidated lists. When a match is detected, it appears in the unified alert inbox and on the vessel's risk profile. Analysts can override matches as false positives or confirmed, and the audit endpoint tracks review rates over time.

## Data sources [#data-sources]

Sanctions screening fuses entities from multiple watchlists. The OpenSanctions default dataset is refreshed daily from the public bulk download and broadens coverage beyond the OFAC / EU / UN core lists to include politically exposed persons (PEPs) and additional national regimes.

| Source                  | Coverage                                            | Refresh | License       |
| ----------------------- | --------------------------------------------------- | ------- | ------------- |
| OFAC SDN                | US Treasury Specially Designated Nationals          | Daily   | Public domain |
| EU consolidated         | EU restrictive measures                             | Daily   | EUPL          |
| UN consolidated         | UN Security Council sanctions                       | Daily   | Public domain |
| OpenSanctions `default` | Consolidated sanctions + PEPs across global regimes | Daily   | CC-BY 4.0     |

OpenSanctions entities are stored in canonical [FollowTheMoney](https://www.opensanctions.org/docs/entities/) JSON. Match candidates use trigram similarity on the entity caption, then are reconciled against vessel ownership graphs before producing an alert. Attribution: data provided by [OpenSanctions](https://www.opensanctions.org/).

## Sanctions overrides [#sanctions-overrides]

### `GET` `/api/v1/sanctions/overrides` [#get-apiv1sanctionsoverrides]


  Requires an API key on a paid analyst plan — tier 

  `pro`

  , 

  `supply_chain_risk`

  , 

  `professional`

  , or 

  `admin`

  . Free and starter-tier keys get 

  `402`

  .


List analyst overrides on sanctions matches. Use this to review false positive determinations and confirmed matches.

**Parameters**

| Name         | Type   | Required | Description                                |
| ------------ | ------ | -------- | ------------------------------------------ |
| `imo`        | string |          | Filter by IMO number                       |
| `dedupe_key` | string |          | Filter by specific match deduplication key |
| `limit`      | number |          | Default 50, max 200                        |

**Response**

```json
{
  "overrides": [],
  "count": 0
}
```

Each `overrides` entry carries `dedupe_key`, `imo_number`, `sanctioned_entity`, `list_source`, `override_status`, `suppression_until`, `reason`, `created_by`, `last_seen_confidence`, `ubo_triangulation`, `updated_at`.

**Errors**

* `402` — API key's tier isn't `pro`/`supply_chain_risk`/`professional`/`admin`: `{ "error": "Sanctions override requires a paid analyst plan", "tier": "..." }`
* `500` — internal error

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/sanctions/overrides?imo=9622629
```

### `POST` `/api/v1/sanctions/overrides` [#post-apiv1sanctionsoverrides]


  Requires an API key on a paid analyst plan — tier 

  `pro`

  , 

  `supply_chain_risk`

  , 

  `professional`

  , or 

  `admin`

  . Free and starter-tier keys get 

  `402`

  .


Create or update an override on a sanctions match. The override persists and is factored into the vessel's risk score.

**Parameters**

| Name               | Type   | Required | Description                                                                                                                                                                                                          |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dedupe_key`       | string |          | Match deduplication key from the original alert. If omitted, it's derived from `match` instead (falls back to a generic key if `match` is also empty, so this is not enforced as strictly required).                 |
| `override_status`  | string | ✓        | `false_positive` or `confirmed_match`                                                                                                                                                                                |
| `match`            | object |          | `{ imo_number, sanctioned_entity, list_source, vessel_name, match_type, raw_data }`. Used to derive `dedupe_key` when it's omitted, and to recompute `last_seen_confidence` / `ubo_triangulation` on the stored row. |
| `suppression_days` | number |          | Only applies when `override_status` is `false_positive`. Days until the suppression expires (`suppression_until`). Default 3650.                                                                                     |
| `reason`           | string |          | Analyst explanation                                                                                                                                                                                                  |

**Response**

```json
{
  "override": {}
}
```

The handler selects `*` from `sanctions_match_overrides`, so `override` returns the full row.

**Errors**

* `400` — invalid JSON payload, or `override_status` missing/not `false_positive`/`confirmed_match`
* `402` — API key's tier isn't `pro`/`supply_chain_risk`/`professional`/`admin`
* `500` — internal error

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/sanctions/overrides \
  -d '{
    "dedupe_key": "9622629:ofac:sdn_entity_123",
    "override_status": "false_positive",
    "reason": "Name similarity only — different registered owner confirmed via Equasis."
  }'
```

***

## Audit metrics [#audit-metrics]

### `GET` `/api/v1/sanctions/audit` [#get-apiv1sanctionsaudit]


  Requires API key.


Weekly audit metrics for sanctions screening: how many matches were reviewed, confirmed, or marked as false positives. Use this to track analyst review rates and model accuracy.

**Parameters**

| Name    | Type   | Required | Description                                              |
| ------- | ------ | -------- | -------------------------------------------------------- |
| `weeks` | number |          | Number of weeks of history to return. Default 8, max 26. |

**Response**

```json
{
  "auto_match_count_snapshot": 245,
  "weeks": 8,
  "latest": null,
  "weekly": []
}
```

`auto_match_count_snapshot` is the total row count in `sanctioned_ownership_matches`. `latest` (the most recent week, or `null` if none fall in range) and each `weekly` entry carry `week_start`, `analyst_reviewed`, `analyst_confirmed`, `analyst_false_positive`, `confirmation_rate_reviewed`, `confirmation_rate_vs_auto`.

**Errors**

* `500` — internal error (override query failed)

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/sanctions/audit?weeks=12
```


# Sentinel-1 catalog coverage (/overwatch/api/sar-coverage)



Check whether the Copernicus catalog lists Sentinel-1 radar products near a location and time.


  This endpoint returns catalog metadata only. It does not download or process image pixels, identify a vessel, confirm a position or transit, or verify a dark-fleet event.


## `GET` `/api/v1/sar-coverage` [#get-apiv1sar-coverage]


  Requires an Overwatch API key.


**Parameters**

| Name     | Type   | Required | Description                                                                                                                        |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `lat`    | number | ✓        | Latitude, -90 to 90.                                                                                                               |
| `lng`    | number | ✓        | Longitude, -180 to 180.                                                                                                            |
| `date`   | string |          | ISO date (`YYYY-MM-DD`) or full UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. Invalid values return `400`. |
| `radius` | number |          | Search radius in kilometers. Defaults to 50; must be greater than 0 and no more than 500.                                          |

**Response**

```json
{
  "has_coverage": false,
  "products": [],
  "closest_pass_hours": null,
  "verification_potential": "none",
  "query": {
    "lat": 0,
    "lng": 0,
    "date": "2026-04-28T00:00:00.000Z",
    "radius_km": 50
  },
  "tier": "pro"
}
```

Each `products` entry carries `name`, `start`, `size_mb`, and `online`. `verification_potential` is one of `high`, `medium`, `low`, or `none`.

The `verification_potential` value summarizes catalog timing and spatial coverage. It is not a detection confidence score.

**Errors**

* `400` — Invalid `lat`, `lng`, `radius`, or `date`.
* `401` — Missing or invalid API key.
* `502` — Upstream Copernicus catalog request failed.
* `500` — Internal server error.

**Example**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/sar-coverage?lat=VALUE&lng=VALUE"
```

## Safe interpretation [#safe-interpretation]

Use a positive result to decide whether an independent imagery workflow is worth pursuing. Do not turn `has_coverage: true` into a claim that Overwatch observed a vessel.

For the supported AIS-based transit workflow and the current radar boundary, see [Chokepoint transits](/overwatch/methodology/chokepoint-transits).


# Satellite Imagery (/overwatch/api/satellite)



MODIS + Sentinel-2 NDVI crop health, yield estimates, and production forecasts.

## `GET` `/api/v1/satellite/regions` [#get-apiv1satelliteregions]

All monitored crop regions with latest NDVI and health assessments.

**Response**

```json
{
  "tier": "pro",
  "regions": []
}
```

Each `regions` entry carries `id`, `slug`, `name`, `country`, `primary_crops`, `planted_area_ha`, `feeds_ports`, `metadata`, plus computed `latest_ndvi` and `health_assessments` fields.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/satellite/regions
```

## `GET` `/api/v1/satellite/health` [#get-apiv1satellitehealth]

Crop health assessments with NDVI deviation and yield estimates.

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `region` | string |          | Region slug                                                                                           |
| `status` | string |          | Health status filter                                                                                  |
| `crop`   | string |          | Crop type                                                                                             |
| `cursor` | number |          | Pagination offset (default 0)                                                                         |
| `limit`  | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "tier": "pro",
  "assessments": [],
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `assessments` entry carries `id`, `region_slug`, `region_name`, `country`, `assessment_date`, `crop`, `health_status`, `ndvi_current`, `ndvi_historical_avg`, `ndvi_deviation_pct`, `yield_estimate_t_ha`, `production_estimate_tons`, `planted_area_ha`, `confidence`, `methodology`, `created_at`.

**Errors**

* `404` — Region not found (when `region` doesn't resolve to a known slug)
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/satellite/health?region=VALUE&status=VALUE
```

## `GET` `/api/v1/satellite/production` [#get-apiv1satelliteproduction]

Production forecasts linked to port export estimates.

**Parameters**

| Name     | Type   | Required | Description                                                                                           |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `region` | string |          | Region slug                                                                                           |
| `port`   | string | ✓        | Port slug                                                                                             |
| `crop`   | string |          | Crop type                                                                                             |
| `cursor` | number |          | Pagination offset (default 0)                                                                         |
| `limit`  | number |          | Default 100. Clamped to the caller's tier ceiling: public/free 20, starter 100, pro 500, admin 10000. |

**Response**

```json
{
  "tier": "pro",
  "forecasts": [],
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}
```

Each `forecasts` entry carries `id`, `region_slug`, `region_name`, `country`, `port_slug`, `port_name`, `crop`, `forecast_date`, `season`, `production_estimate_tons`, `yoy_change_pct`, `export_estimate_tons`, `export_timeline_weeks`, `confidence`, `metadata`, `created_at`.

**Errors**

* `400` — `port` is required
* `404` — Port not found, or region not found (when `region` doesn't resolve to a known slug)
* `500` — internal server error

**Example**

```bash
curl -X GET \
  https://www.axiomoverwatch.io/api/v1/satellite/production?region=VALUE&port=VALUE
```


# SDKs & MCP (/overwatch/api/sdk)



Client libraries and AI agent integration.

Python SDK

```bash
pip install axiom-overwatch
```

```python
from axiom_overwatch import AxiomClient

client = AxiomClient(api_key="your-key")
positions = client.positions(port="santos")
df = client.to_dataframe(positions)
```

MCP Server (AI Agents)

Give Claude, GPT, or any MCP-compatible AI agent access to maritime intelligence.

```bash
AXIOM_API_KEY=your-key npx @axiom/mcp-server
```

12 tools: vessel positions, export estimates, congestion, risk scores, dark fleet events, trade flows, mirror discrepancies, sanctions, commodity prices, forecasts, ports, crop health.


# Signal intelligence (/overwatch/api/signals)



Explainability breakdowns and analyst feedback calibration for spoofing, cargo, and motif signals.

Use these endpoints to understand why a signal was generated, what data sources contributed to it, and to review how analysts have classified past signals for threshold tuning.

## `GET` `/api/v1/signals/explainability` [#get-apiv1signalsexplainability]


  Requires API key. Any authenticated tier can call this — despite the name, the handler does not gate on analyst/admin access (unlike the other three endpoints on this page).


Returns human-readable explainability breakdowns for three signal types on a vessel: spoofing, cargo estimation, and temporal motif detection. Any of `spoofing`, `cargo`, or `motif` is `null` if no matching row exists for the vessel (or at all, when `imo` is omitted).

Each breakdown includes detector version, score components, source hierarchy or signature families, evidence timeline, and confidence figures. Use this to audit detection logic or build transparency reports.

**Parameters**

| Name  | Type   | Required | Description                                                                                                                         |
| ----- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `imo` | string |          | 7-digit IMO number. Omit (or pass a value that isn't exactly 7 digits) to return the latest signal of each type across all vessels. |

**Response**

```json
{
  "imo": "9876543",
  "spoofing": {
    "vesselName": "string",
    "imo": "9876543",
    "violationType": "froude_number",
    "impliedSpeedKnots": 0,
    "maxAllowedSpeedKnots": 0,
    "distanceNm": 0,
    "gapHours": 0,
    "detectedAt": "2026-04-18T03:22:00Z",
    "violationReason": "string",
    "confidence": 0,
    "detectorVersion": "detect-dark-events@2026-04",
    "dominantFamily": null,
    "severity": "high",
    "explanation": {
      "detectorVersion": "detect-dark-events@2026-04",
      "subtype": null,
      "dominantFamily": null,
      "firedFamilies": [],
      "coordinatedSpoofConfidence": 0,
      "kinematicAnomalyScore": 0,
      "temporalIdentityScore": 0,
      "signatures": [],
      "scoreComponents": [],
      "evidenceTimeline": []
    }
  },
  "cargo": {
    "vesselName": "string",
    "imo": "9876543",
    "draftArrival": 0,
    "draftDeparture": 0,
    "maxDraft": 0,
    "estimatedTons": 0,
    "method": "hydrostatics",
    "confidenceLabel": "medium",
    "variancePct": 0.035,
    "densityCorrection": 1,
    "vesselType": "unknown",
    "uncertaintyLow": 0,
    "uncertaintyHigh": 0,
    "detectorVersion": "cargo-estimation@2026-04",
    "explanation": {
      "detectorVersion": "cargo-estimation@2026-04",
      "method": "hydrostatics",
      "methodLabel": "Physics-Informed Hydrostatics",
      "confidenceLabel": "medium",
      "uncertaintyLow": 0,
      "uncertaintyHigh": 0,
      "variancePct": 0.035,
      "draftChangeMeters": 0,
      "sourceHierarchy": [],
      "evidenceTimeline": [],
      "draftSurvey": null
    }
  },
  "motif": {
    "motifName": "string",
    "vesselName": "IMO:9876543",
    "confidence": 0,
    "detectedAt": "2026-04-18T03:22:00Z",
    "isSpurious": false,
    "robustnessScore": 0,
    "refutationRationale": null,
    "detectorVersion": "temporal-watchlist@2026-04",
    "compositeRiskScore": null,
    "confidenceComposition": [],
    "evidenceTimeline": [],
    "explanation": {
      "detectorVersion": "temporal-watchlist@2026-04",
      "motifName": "string",
      "confidence": 0,
      "confidenceLabel": "medium",
      "baseConfidence": 0,
      "compositeRiskScore": null,
      "compositeRiskLabel": null,
      "compositeContributingMotifs": [],
      "confidenceComposition": [],
      "evidenceTimeline": [],
      "pathEdgeIds": []
    }
  },
  "tier": "pro"
}
```

The response is built from application logic, not a raw table row, and uses **camelCase** keys throughout (not snake\_case). `spoofing.violationType` is `froude_number` or `ou_bounding_cone`; `spoofing.explanation.signatures` entries carry `family`, `label`, `fired`, `score`, `reason`, `observed`, `threshold`. `spoofing.explanation.scoreComponents`, `cargo.explanation.evidenceTimeline`/`motif.explanation.evidenceTimeline`, and `motif.explanation.confidenceComposition` entries carry `key`/`title`, `label`/`detail`, `score`, `detail`/`timestamp` (timeline items use `title`, `detail`, `timestamp`; score-style items use `key`, `label`, `score`, `detail`). `cargo.explanation.sourceHierarchy` entries carry `label`, `status`, `detail`. `cargo.explanation.draftSurvey` (when not `null`) carries `arrivalDensityCorrectionFactor`, `departureDensityCorrectionFactor`, `arrivalDeductiblesTons`, `departureDeductiblesTons`, `arrivalNetDisplacementTons`, `departureNetDisplacementTons`.

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/signals/explainability?imo=9876543
```

## `GET` `/api/v1/signals/feedback-calibration` [#get-apiv1signalsfeedback-calibration]


  Requires API key with analyst access — in practice this means an 

  `admin`

  -tier API key (or an internal/dashboard caller); any other tier gets 

  `403`

  .


Aggregated view of all analyst-adjudicated signal feedback across signal types. Use this to build calibration dashboards, track confirmed true positives versus dismissed false positives, and tune detection thresholds.

**Parameters**

| Name          | Type   | Required | Description                                         |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `imo`         | string |          | Filter by vessel IMO                                |
| `status`      | string |          | 'confirmed', 'dismissed', or 'needs\_review'        |
| `signal_type` | string |          | 'dark\_event', 'spoofing\_alert', or 'motif\_alert' |
| `cursor`      | number |          | Pagination offset (default 0)                       |
| `limit`       | number |          | Results per page, 1–1000 (default 200)              |

**Response**

```json
{
  "rows": [],
  "summary": {
    "totalRows": 312,
    "confirmedCount": 198,
    "dismissedCount": 87,
    "needsReviewCount": 27,
    "bySignalType": {
      "dark_event": 145,
      "spoofing_alert": 102,
      "motif_alert": 65
    },
    "byAdjudicationStatus": {
      "confirmed": 198,
      "dismissed": 87,
      "needs_review": 27
    }
  },
  "tier": "admin",
  "pagination": { "limit": 200, "has_more": true, "next_cursor": "200" }
}
```

Each `rows` entry carries `signalType`, `signalId`, `entityId`, `detectedAt`, `adjudicationStatus`, `adjudicationReasonCode`, `analystUpdatedAt`, `confidence`, `severity`, `detectorKind`, `dedupeKey`, `suppressionWindowHours`, `confirmed`, `dismissed`, `needsReview`, `metadata`. `pagination.next_cursor` is a stringified offset (or `null` on the last page), not the `cursor` value itself.

**Errors**

* `403` — `Admin API key required.` (caller's tier isn't `admin` or an internal call)

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/signals/feedback-calibration?status=confirmed&signal_type=spoofing_alert
```

## `GET` `/api/v1/vessels/{imo}/signal-feedback` [#get-apiv1vesselsimosignal-feedback]


  Requires API key with analyst access — in practice this means an 

  `admin`

  -tier API key (or an internal/dashboard caller); any other tier gets 

  `403`

  .


Returns the signal feedback panel for a specific vessel — all recent dark events, spoofing alerts, and motif alerts with their adjudication status. Includes suppression state for repeated signals.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

**Response**

```json
{
  "feedback_items": [
    {
      "signalType": "spoofing_alert",
      "signalId": "abc-123",
      "title": "Spoofing Alert · Combined",
      "summary": "Kinematic anomaly detected",
      "detectedAt": "2026-04-15T08:30:00Z",
      "severity": "high",
      "detectorKey": "combined",
      "adjudicationStatus": "confirmed",
      "adjudicationReasonCode": "confirmed_external_intel",
      "adjudicationReasonLabel": "External intelligence confirmed it",
      "analystNotes": null,
      "analystUpdatedAt": "2026-04-15T09:00:00Z",
      "analystUpdatedBy": "api_key:abc123",
      "suppressionWindowHours": 24,
      "suppressionUntil": "2026-04-16T09:00:00Z",
      "dedupeKey": "spoofing_alert:9876543:combined",
      "suppressedRepeatCount": 3,
      "lastRepeatAt": null
    }
  ],
  "summary": {
    "totalSignals": 12,
    "pendingSignals": 4,
    "adjudicatedSignals": 8,
    "calibration": {
      "totalRows": 8,
      "confirmedCount": 5,
      "dismissedCount": 2,
      "needsReviewCount": 1,
      "bySignalType": { "dark_event": 3, "spoofing_alert": 4, "motif_alert": 1 },
      "byAdjudicationStatus": { "confirmed": 5, "dismissed": 2, "needs_review": 1 }
    }
  },
  "status_options": ["confirmed", "dismissed", "needs_review"],
  "reason_options": [
    { "code": "confirmed_external_intel", "label": "External intelligence confirmed it", "allowedStatuses": ["confirmed"] },
    { "code": "multisource_corroboration", "label": "Corroborated by multiple signals", "allowedStatuses": ["confirmed"] },
    { "code": "expected_behavior", "label": "Expected vessel behavior", "allowedStatuses": ["dismissed"] },
    { "code": "sensor_noise", "label": "Sensor noise or AIS artifact", "allowedStatuses": ["dismissed"] },
    { "code": "insufficient_evidence", "label": "Insufficient evidence", "allowedStatuses": ["dismissed", "needs_review"] },
    { "code": "duplicate_unchanged_alert", "label": "Duplicate unchanged alert", "allowedStatuses": ["dismissed", "needs_review"] },
    { "code": "monitoring_only", "label": "Monitor only for now", "allowedStatuses": ["needs_review"] },
    { "code": "escalated_manual_review", "label": "Escalated for manual review", "allowedStatuses": ["needs_review"] },
    { "code": "other", "label": "Other", "allowedStatuses": ["confirmed", "dismissed", "needs_review"] }
  ],
  "suppression_options_hours": [0, 12, 24, 72, 168],
  "default_suppression_windows_hours": { "confirmed": 24, "dismissed": 72, "needs_review": 12 }
}
```

`reason_options` is an array of objects (`code`, `label`, `allowedStatuses`), not bare strings — each reason code is only valid for the statuses listed in `allowedStatuses`. `suppression_options_hours` is `[0, 12, 24, 72, 168]`. `summary.calibration` and `default_suppression_windows_hours` are not optional — they're always present.

**Errors**

* `403` — `Admin API key required.` (caller's tier isn't `admin` or an internal call)
* `400` — `Invalid IMO number — must be exactly 7 digits.`

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/signal-feedback
```

## `PATCH` `/api/v1/vessels/{imo}/signal-feedback` [#patch-apiv1vesselsimosignal-feedback]


  Requires API key with analyst access — in practice this means an 

  `admin`

  -tier API key (or an internal/dashboard caller); any other tier gets 

  `403`

  .


Submit an analyst adjudication for a signal on a vessel. You can confirm, dismiss, or flag a signal for review, and optionally suppress repeat alerts for a configurable window.

**Parameters**

| Name                       | Type   | Required | Description                                                                                                                                                                                                              |
| -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `imo`                      | string | ✓        | 7-digit IMO number (path param)                                                                                                                                                                                          |
| `signal_type`              | string | ✓        | 'dark\_event', 'spoofing\_alert', or 'motif\_alert'                                                                                                                                                                      |
| `signal_id`                | string | ✓        | Signal identifier                                                                                                                                                                                                        |
| `adjudication_status`      | string | ✓        | 'confirmed', 'dismissed', or 'needs\_review'                                                                                                                                                                             |
| `reason_code`              | string |          | Structured reason (e.g. 'sensor\_noise', 'confirmed\_external\_intel'). Each code is only valid for certain statuses — see `reason_options` on the `GET` endpoint above for the full `code` → `allowedStatuses` mapping. |
| `analyst_notes`            | string |          | Free-form notes                                                                                                                                                                                                          |
| `suppression_window_hours` | number |          | Hours to suppress similar signals, clamped to 0–720. Defaults by status when omitted: `confirmed` 24h, `dismissed` 72h, `needs_review` 12h.                                                                              |

**Response**

```json
{
  "signal_feedback": {
    "signalType": "spoofing_alert",
    "signalId": "abc-123",
    "adjudicationStatus": "confirmed",
    "adjudicationReasonCode": "confirmed_external_intel",
    "analystNotes": null,
    "suppressionWindowHours": 24,
    "suppressionUntil": "2026-04-16T09:00:00Z",
    "dedupeKey": "spoofing_alert:9876543:combined",
    "updatedAt": "2026-04-15T09:00:00Z"
  }
}
```

The response nests everything under `signal_feedback` with camelCase keys — there is no top-level `ok` field.

**Errors**

* `403` — `Admin API key required.` (caller's tier isn't `admin` or an internal call)
* `400` — `Invalid IMO number — must be exactly 7 digits.`
* `400` — `Invalid JSON body.`
* `400` — `signal_type, signal_id, and adjudication_status are required.`
* `400` — `reason_code is invalid.`
* `400` — `reason_code is not valid for the selected adjudication_status.`
* `400` — `Signal does not belong to the requested vessel.`
* `404` — Signal not found (Supabase lookup error message, or `Signal not found.`)
* `500` — Database update error

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/vessels/9876543/signal-feedback \
  -d '{"signal_type":"spoofing_alert","signal_id":"abc-123","adjudication_status":"confirmed","reason_code":"confirmed_external_intel"}'
```


# Trade Flows (/overwatch/api/trade-flows)



Bilateral commodity trade data from UN Comtrade, mirror data discrepancy detection, entity resolution, and sanctions cross-referencing.

## `GET` `/api/v1/trade-flows` [#get-apiv1trade-flows]


  Requires API key.


Bilateral trade flow data. Use ?view param for different analyses.

**Parameters**

| Name        | Type   | Required | Description                                                                                                                        |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `view`      | string |          | 'flows' (default) \| 'mirror' \| 'sanctions' \| 'entity'                                                                           |
| `exporter`  | string |          | Exporter country name filter (flows view only)                                                                                     |
| `importer`  | string |          | Importer country name filter (flows view only)                                                                                     |
| `commodity` | string |          | Commodity name filter (e.g. Wheat, Soybeans) (flows/mirror views only)                                                             |
| `period`    | string |          | Year filter (e.g. '2024') (flows/mirror views only)                                                                                |
| `limit`     | number |          | Max results per page, default 50, clamped to the API key's tier ceiling: 20 (free/public), 100 (starter), 500 (pro), 10000 (admin) |
| `cursor`    | number |          | Pagination offset. Default 0; pass the previous response's `pagination.next_cursor` to fetch the next page                         |

**Response**

```json
{
  "flows": [],
  "count": 0,
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `flows` entry carries `reporter_name`, `partner_name`, `commodity_name`, `flow_direction`,
`period`, `period_type`, `net_weight_kg`, `value_usd`. The `mirror`, `sanctions`, and `entity`
views below return a different envelope — see each section.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/trade-flows?view=VALUE&exporter=VALUE
```

## `GET` `/api/v1/trade-flows?view=mirror` [#get-apiv1trade-flowsviewmirror]

Mirror data discrepancies: exporter-reported vs importer-reported volumes for the same commodity/country pair. Large discrepancies signal trade re-routing or misclassification.

**Response**

```json
{
  "discrepancies": [],
  "count": 0,
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `discrepancies` entry returns the full `trade_mirror_discrepancies` row (`select('*')`).

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/trade-flows?view=mirror
```

## `GET` `/api/v1/trade-flows?view=sanctions` [#get-apiv1trade-flowsviewsanctions]

Vessels matched against OFAC sanctions list via IMO, MMSI, or name-based entity resolution.

**Parameters**

| Name                 | Type    | Required | Description                                                    |
| -------------------- | ------- | -------- | -------------------------------------------------------------- |
| `include_suppressed` | boolean |          | Include matches suppressed as false positives. Default `false` |

**Response**

```json
{
  "matches": [],
  "count": 0,
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null },
  "suppressed_count": 0,
  "match_types": { "direct_imo": 0, "mmsi": 0, "name": 0 },
  "confidence_bands": { "high": 0, "medium": 0, "low": 0 }
}
```

Each `matches` entry returns the full `sanctioned_ownership_matches` row plus computed
`dedupe_key`, `match_confidence`, `confidence_band`, `imo_anchored`, `ubo_triangulation`,
`is_suppressed_false_positive` fields.

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/trade-flows?view=sanctions
```

## `GET` `/api/v1/trade-flows?view=entity` [#get-apiv1trade-flowsviewentity]

Supply chain entity graph: vessels linked to owners, ports, sanctions, P\&I coverage, and dark fleet history.

**Parameters**

| Name  | Type   | Required | Description          |
| ----- | ------ | -------- | -------------------- |
| `imo` | string |          | Filter by IMO number |

**Response**

```json
{
  "entities": [],
  "count": 0,
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `entities` entry returns the full `supply_chain_entities` row (`select('*')`).

**Errors**

* `500` — internal server error

**Example**

```bash
curl -X GET \
  -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/trade-flows?view=entity&imo=9622629
```


# Beneficial ownership (/overwatch/api/ubo)



Trace the ownership chain of any vessel from registered owner through to ultimate beneficial owner. The UBO graph resolves corporate structures and cross-references ownership entities against sanctions lists, showing where a vessel sits in the broader network.

## `GET` `/api/v1/ubo/vessel/{imo}` [#get-apiv1ubovesselimo]


  Requires API key on a paid plan (

  `pro`

  , 

  `admin`

  , 

  `supply_chain_risk`

  , or 

  `professional`

   tier).


Returns the full beneficial ownership graph for a vessel, including the sanctions network — all entities in the ownership chain that have sanctions matches.

**Parameters**

| Name  | Type   | Required | Description                     |
| ----- | ------ | -------- | ------------------------------- |
| `imo` | string | ✓        | 7-digit IMO number (path param) |

**Response**

```json
{
  "vessel": {
    "imo_number": "9622629",
    "name": "MV Meridian"
  },
  "graph": {
    "nodes": [],
    "edges": []
  },
  "sanctions_network": {
    "flagged_entities": [],
    "linked_vessels": []
  },
  "tier": "pro"
}
```

Each `graph.nodes` entry carries `id`, `label`, `entity_type`. Each `graph.edges` entry carries `id`, `source`, `target`, `relationship`, `source_system`, `confidence`. `sanctions_network.flagged_entities` is an array of sanctioned entity names found in the ownership chain; each `sanctions_network.linked_vessels` entry carries `imo_number`, `vessel_name`, `sanctioned_entity`, `list_source`, `match_type`.

**Errors**

* `400` — `imo` is not exactly 7 digits.
* `402` — API key tier is not `pro`, `admin`, `supply_chain_risk`, or `professional` — the UBO graph is a paid-only feature.
* `404` — No vessel found for that IMO.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/ubo/vessel/9622629
```

## `GET` `/api/v1/ubo/vessels` [#get-apiv1ubovessels]


  Requires API key.


Search for vessels connected to a UBO entity name. Traverses the ownership graph from a fuzzy substring match on the entity name up to 3 hops, then returns matching vessels ordered by risk score (highest first).

**Parameters**

| Name     | Type   | Required | Description                                                  |
| -------- | ------ | -------- | ------------------------------------------------------------ |
| `entity` | string | ✓        | Entity name (or fragment) to search the ownership graph for. |

**Response**

```json
{
  "entity": "XYZ Management",
  "count": 0,
  "vessels": [],
  "tier": "pro"
}
```

Each `vessels` entry carries `imo_number`, `name`, `flag`, `risk_tier`, `risk_score`.

**Errors**

* `400` — Missing required query parameter: `entity`.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/ubo/vessels?entity=XYZ%20Management"
```

***

## GLEIF ultimate parent chain [#gleif-ultimate-parent-chain]

Overwatch ingests the [GLEIF Level 2 Relationship Records](https://www.gleif.org/en/lei-data/gleif-golden-copy/download-the-golden-copy) golden copy weekly. Every active **direct** and **ultimate** accounting-consolidation relationship between Legal Entity Identifiers (LEIs) lands in the `gleif_relationships` table, and a Postgres function walks the consolidation graph from a child LEI up to its ultimate parents.

Use this when you have an LEI on an entity in a vessel's ownership chain — registered owner, beneficial owner, or anything in between — and need to resolve the accounting-consolidation parent chain above it. The output is the canonical input to manual UBO investigations and to the [sanctions screening](/overwatch/api/sanctions) pipeline.

**Source**: GLEIF RR-CDF (Relationship Record Common Data Format) JSON golden copy. CC0 Public Domain. Refreshed weekly.

### `get_ultimate_parent_chain(p_lei)` [#get_ultimate_parent_chainp_lei]

Recursive Postgres function. Follows `ACTIVE` GLEIF relationships of type `IS_DIRECTLY_CONSOLIDATED_BY` and `IS_ULTIMATELY_CONSOLIDATED_BY` from the input LEI up to each terminal parent. Returns one row per hop.

| Behavior            | Value                                         |
| ------------------- | --------------------------------------------- |
| Direction           | Child → parent (upward)                       |
| Relationship filter | `IS_%CONSOLIDATED_BY`, `status = 'ACTIVE'`    |
| Depth cap           | 10 hops (hard)                                |
| Cycle guard         | Stops re-entering any LEI already on the path |
| Input normalization | `upper(trim(p_lei))`                          |

**Parameters**

| Name    | Type | Required | Description                                                                                          |
| ------- | ---- | -------- | ---------------------------------------------------------------------------------------------------- |
| `p_lei` | text | ✓        | 20-character ISO 17442 LEI of the child entity. Case-insensitive; surrounding whitespace is trimmed. |

**Returns** (table)

| Column              | Type        | Description                                                       |
| ------------------- | ----------- | ----------------------------------------------------------------- |
| `depth`             | integer     | Hop count from the input LEI. `1` = direct parent.                |
| `relationship_id`   | text        | GLEIF relationship record identifier.                             |
| `start_node_lei`    | text        | LEI of the child in this hop.                                     |
| `end_node_lei`      | text        | LEI of the parent in this hop.                                    |
| `relationship_type` | text        | `IS_DIRECTLY_CONSOLIDATED_BY` or `IS_ULTIMATELY_CONSOLIDATED_BY`. |
| `status`            | text        | Always `ACTIVE` (inactive relationships are filtered out).        |
| `path`              | text\[]     | LEIs visited on the way to this row, starting with the input LEI. |
| `occurred_at`       | timestamptz | Publication timestamp of the underlying GLEIF record.             |
| `source_uri`        | text        | URI of the source CDF JSON file.                                  |

**Example (Supabase client)**

```ts
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

const { data, error } = await supabase.rpc('get_ultimate_parent_chain', {
  p_lei: '529900T8BM49AURSDO55',
});

// data: [
//   { depth: 1, end_node_lei: '...', relationship_type: 'IS_DIRECTLY_CONSOLIDATED_BY', ... },
//   { depth: 2, end_node_lei: '...', relationship_type: 'IS_ULTIMATELY_CONSOLIDATED_BY', ... },
// ]
```

**Example (Postgres / SQL)**

```sql
SELECT depth, end_node_lei, relationship_type, path
FROM public.get_ultimate_parent_chain('529900T8BM49AURSDO55')
ORDER BY depth;
```


  The function is exposed to `anon`, `authenticated`, and `service_role`. Call it via the Supabase REST/PostgREST RPC interface, the Supabase JS / Python client, or directly in SQL against a read replica. There is no REST endpoint wrapper yet — the vessel-scoped `/api/v1/ubo/vessel/{imo}` graph above remains the recommended starting point when you are working from an IMO rather than an LEI.



# Vessels & Positions (/overwatch/api/vessels)



Vessel registry and real-time AIS positions.

## `GET` `/api/v1/vessels` [#get-apiv1vessels]

List vessels that have visited a given port, optionally filtered by type, IMO, or MMSI. Returns IMO, name, DWT, flag, dimensions.

**Parameters**

| Name     | Type   | Required | Description                                                                                              |
| -------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `port`   | string | ✓        | Port slug                                                                                                |
| `type`   | string |          | Vessel type filter                                                                                       |
| `imo`    | string |          | Filter to a single IMO number                                                                            |
| `mmsi`   | string |          | Filter to a single MMSI number                                                                           |
| `cursor` | string |          | Pagination cursor — pass the previous response's `pagination.next_cursor`                                |
| `limit`  | number |          | Default 50. Capped per-tier via `clampLimit`: 20 (free/public), 100 (starter), 500 (pro), 10,000 (admin) |

**Response**

```json
{
  "vessels": [],
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `vessels` entry carries `imo_number`, `mmsi`, `name`, `vessel_type`, `dwt`, `max_draft`, `length`, `beam`, `flag`.

**Errors**

| Status | When                                                                                                                    |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | `port` missing                                                                                                          |
| `404`  | `port` slug not found                                                                                                   |
| `500`  | Vessel-visit or vessel lookup failed                                                                                    |
| `503`  | Port lookup temporarily unavailable (PostgREST schema-cache failure after retry); served with `Cache-Control: no-store` |

**Example**


  
    ```bash cURL
    curl -X GET \
      "https://www.axiomoverwatch.io/api/v1/vessels?port=santos&type=bulk_carrier"
    ```
  

  
    ```python Python
    import requests

    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/vessels",
        params={"port": "santos", "type": "bulk_carrier"},
    )
    data = res.json()  # {"vessels": [...], "tier": "pro", "pagination": {...}}
    ```
  

  
    ```js Node
    const url = new URL("https://www.axiomoverwatch.io/api/v1/vessels");
    url.searchParams.set("port", "santos");
    url.searchParams.set("type", "bulk_carrier");

    const data = await fetch(url).then((r) => r.json());
    ```
  


## `GET` `/api/v1/positions` [#get-apiv1positions]

Latest AIS positions for all vessels at a port. Includes course, speed, draft, destination, nav status, and timestamp.

**Parameters**

| Name     | Type   | Required | Description                                                                                              |
| -------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `port`   | string | ✓        | Port slug                                                                                                |
| `cursor` | string |          | Pagination cursor — pass the previous response's `pagination.next_cursor`                                |
| `limit`  | number |          | Default 50. Capped per-tier via `clampLimit`: 20 (free/public), 100 (starter), 500 (pro), 10,000 (admin) |


  Free/public tier responses have 

  `latitude`

   and 

  `longitude`

   stripped (

  `redactPositions`

  ) — only starter/pro/admin tiers receive exact coordinates.


**Response**

```json
{
  "positions": [],
  "tier": "pro",
  "pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
```

Each `positions` entry carries `imo_number`, `latitude`, `longitude`, `speed`, `course`, `draft`, `destination`, `nav_status`, `timestamp`, plus the joined `name` and `vessel_type`.

**Errors**

| Status | When                                                                                                                    |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | `port` missing                                                                                                          |
| `404`  | `port` not found                                                                                                        |
| `500`  | Vessel-visit, position, or vessel lookup failed                                                                         |
| `503`  | Port lookup temporarily unavailable (PostgREST schema-cache failure after retry); served with `Cache-Control: no-store` |

**Example**


  
    ```bash cURL
    curl -X GET \
      "https://www.axiomoverwatch.io/api/v1/positions?port=santos"
    ```
  

  
    ```python Python
    import requests

    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/positions",
        params={"port": "santos"},
    )
    data = res.json()  # {"positions": [...], "tier": "pro", "pagination": {...}}
    ```
  

  
    ```js Node
    const url = new URL("https://www.axiomoverwatch.io/api/v1/positions");
    url.searchParams.set("port", "santos");

    const data = await fetch(url).then((r) => r.json());
    ```
  


## `GET` `/api/v1/positions/latest` [#get-apiv1positionslatest]

GeoJSON `FeatureCollection` of the latest known vessel positions, scoped to a port or a bounding-box viewport (\~18K vessels tracked total). Powers the public live vessel map. Public, no auth required, CDN-cached for 5 minutes (`Cache-Control: public, s-maxage=300, stale-while-revalidate=60`).

Use this for a map, a heatmap, or a periodic dashboard refresh, scoped to either a `port` or a `west`/`south`/`east`/`north` viewport. A request supplying neither returns `400` — there is no unscoped "every vessel worldwide" call.

**Parameters**

| Name    | Type   | Required | Description                                                                                                                                                                                                                      |
| ------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`  | string |          | Port slug — filters to that port's geofence (via the `latest_positions_for_port` RPC, capped at 5,000 vessels)                                                                                                                   |
| `type`  | string |          | Filter by vessel type (e.g. `bulk_carrier`, `tanker`, `container`)                                                                                                                                                               |
| `west`  | number |          | Western longitude of bounding box                                                                                                                                                                                                |
| `south` | number |          | Southern latitude of bounding box                                                                                                                                                                                                |
| `east`  | number |          | Eastern longitude of bounding box                                                                                                                                                                                                |
| `north` | number |          | Northern latitude of bounding box                                                                                                                                                                                                |
| `zoom`  | number |          | Client viewport zoom level. Only applies when querying by bounding box (ignored when `port` is set); below zoom `6` the response is a grid-decimated sample (one vessel per cell, capped at 4,000) instead of every matching row |

Provide either `port` or a complete `west`+`south`+`east`+`north` bounding box — a request with neither returns `400` ("port or viewport bounds are required"). Partial bounds (fewer than all four) are treated as no bounds at all. Bounding boxes that cross the antimeridian (where `west` > `east`) are supported.

**Response**

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-46.30, -23.97] },
      "properties": {
        "imo": "9876543",
        "name": "EXAMPLE CARRIER",
        "vessel_type": "bulk_carrier",
        "flag": "PA",
        "speed": 12.4,
        "course": 87,
        "draft": 11.2,
        "destination": "BR SSZ",
        "nav_status": "under way using engine",
        "timestamp": "2026-04-27T18:42:11Z",
        "last_seen": "2026-04-27T18:42:11Z",
        "coverage_source": "live_7d",
        "dwt": 81600,
        "length": 229,
        "beam": 32,
        "build_year": 2014,
        "photo_url": "https://..."
      }
    }
  ],
  "meta": {
    "total_vessel_count": 18243,
    "viewport_vessel_count": 18243,
    "rendered_vessel_count": 18243,
    "updated_at": "2026-04-27T18:42:30Z",
    "cache_ttl": 300,
    "viewport_applied": false,
    "port": null,
    "coordinates": "exact",
    "truncated": false,
    "sampled": false
  }
}
```

`properties.timestamp` and `properties.last_seen` carry the same value; `properties.coverage_source` is `live_7d` or `last_known`. `meta.coordinates` is always `"exact"` on this public route — the anti-scrape control is the row cap (`meta.truncated`), not coordinate redaction.

The full global payload is roughly 800 KB gzipped. Refresh no more than once every 5 minutes — additional requests inside that window are served from the CDN cache and return identical data. Cache-miss requests are additionally rate-limited per IP at 30/minute and 3,000/day; exceeding either returns `429` with a `Retry-After` header.


  When the PostgREST schema cache is temporarily unavailable, the system retries once before returning a `503` degraded response. The `503` is served with `Cache-Control: no-store` (overriding the normal CDN cache) and includes CORS headers so browser-based map clients can surface the error cleanly. Authenticated requests to this route retain a private `500` contract for the same condition.


**Errors**

| Status | When                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Neither `port` nor a complete bounding box supplied                                                                                                          |
| `404`  | `port` supplied but not found                                                                                                                                |
| `429`  | Per-IP rate limit exceeded (30/min or 3,000/day on cache misses)                                                                                             |
| `500`  | Query failure                                                                                                                                                |
| `503`  | PostgREST schema cache unavailable after retry (port lookup, viewport read, or sampled viewport RPC); served with `Cache-Control: no-store` and CORS headers |

**Example**


  
    ```bash cURL
    # Worldwide viewport (all four bounds required — there is no unscoped global call)
    curl "https://www.axiomoverwatch.io/api/v1/positions/latest?west=-180&south=-85&east=180&north=85"

    # Tankers only, in a Gulf of Mexico bounding box
    curl "https://www.axiomoverwatch.io/api/v1/positions/latest?type=tanker&west=-98&south=18&east=-80&north=31"

    # A single port's geofence
    curl "https://www.axiomoverwatch.io/api/v1/positions/latest?port=santos"
    ```
  

  
    ```python Python
    import requests

    # A single port's geofence
    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/positions/latest",
        params={"port": "santos"},
    )
    geojson = res.json()  # GeoJSON FeatureCollection + meta

    # Worldwide viewport (all four bounds required)
    world = requests.get(
        "https://www.axiomoverwatch.io/api/v1/positions/latest",
        params={"west": -180, "south": -85, "east": 180, "north": 85},
    ).json()
    ```
  

  
    ```js Node
    // A single port's geofence
    const url = new URL("https://www.axiomoverwatch.io/api/v1/positions/latest");
    url.searchParams.set("port", "santos");
    const geojson = await fetch(url).then((r) => r.json()); // GeoJSON FeatureCollection

    // Worldwide viewport (all four bounds required)
    const world = new URL("https://www.axiomoverwatch.io/api/v1/positions/latest");
    world.searchParams.set("west", "-180");
    world.searchParams.set("south", "-85");
    world.searchParams.set("east", "180");
    world.searchParams.set("north", "85");
    const global = await fetch(world).then((r) => r.json());
    ```
  


## `GET` `/api/v1/ais/{provider}/{imo}/location/latest` [#get-apiv1aisproviderimolocationlatest]

Public, no-auth, citable lookup of the latest known position for a single vessel. Reads from a deduped materialized view (one row per IMO per source) and returns a JSON-LD payload that AI ingestion pipelines and academic citations can pick up directly.

Use this when you need a single vessel's most recent fix and want a stable, machine-readable contract you can reference from a paper, news article, or LLM training pipeline. For port-wide snapshots use `/api/v1/positions`; for the global feed use `/api/v1/positions/latest`.

* No API key required.
* Open CORS (`Access-Control-Allow-Origin: *`).
* IP-keyed rate limiting: 60 requests/minute and 1,000 requests/UTC day.
* Cached at the edge for 60 seconds (`Cache-Control: public, max-age=60`).
* Released under CC-BY 4.0 with attribution.

A machine-readable OpenAPI 3.1 spec for this endpoint is published at [`https://www.axiomoverwatch.io/openapi/positions.yaml`](https://www.axiomoverwatch.io/openapi/positions.yaml).

**Path parameters**

| Name       | Type   | Required | Description                                                                                                                          |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `provider` | string | ✓        | AIS source. One of `aishub`, `aisstream`, `satellite`, `spire`, or `any`. Use `any` to get the freshest position across all sources. |
| `imo`      | string | ✓        | 7-digit IMO number, zero-padded if needed (matches `^[0-9]{7}$`).                                                                    |

**Response headers**

Every successful response includes rate-limit headers:

* `X-RateLimit-Limit-Minute`, `X-RateLimit-Remaining-Minute`
* `X-RateLimit-Limit-Day`, `X-RateLimit-Remaining-Day`

`429` responses include `Retry-After` (seconds until the offending bucket resets).

**Response (`200`)**

```json
{
  "@context": "https://schema.org",
  "@type": "GeoCoordinates",
  "imo_number": "9876543",
  "vessel_name": "EXAMPLE TRADER",
  "vessel_type": "Bulk Carrier",
  "flag": "PA",
  "latitude": -23.9876,
  "longitude": -46.3214,
  "speed_kt": 0.1,
  "course_deg": 187.4,
  "draft_m": 12.4,
  "destination": "SANTOS",
  "nav_status": "At anchor",
  "timestamp": "2026-04-28T18:42:11.000Z",
  "source": "aishub",
  "freshness_seconds": 312,
  "attribution": {
    "name": "Axiom Overwatch",
    "url": "https://axiomoverwatch.io",
    "cite_as": "Axiom Overwatch — vessel position lookup for IMO 9876543, 2026-04-28T18:42:11.000Z",
    "license": "CC-BY 4.0 with attribution"
  }
}
```

`freshness_seconds` is the age of the position relative to request time. Stale positions (vessel hasn't broadcast in a while) are still returned — inspect `freshness_seconds` and `timestamp` to decide whether to trust the fix. The self-declared `destination` field is frequently inaccurate or deliberately deceptive; for due-diligence work prefer the paid-tier destination-reliability scoring.

**Error responses**

| Status | When                                                        |
| ------ | ----------------------------------------------------------- |
| `400`  | `provider` not in the allowed set, or `imo` is not 7 digits |
| `404`  | No recent position for this IMO + provider combination      |
| `429`  | Rate limit exceeded (per-minute or per-day)                 |
| `500`  | Backing materialized view lookup failed                     |

**Example**


  
    ```bash cURL
    # Freshest position across any source
    curl https://www.axiomoverwatch.io/api/v1/ais/any/9876543/location/latest

    # Filter to a single source
    curl https://www.axiomoverwatch.io/api/v1/ais/satellite/9876543/location/latest
    ```
  

  
    ```python Python
    import requests

    # Freshest position across any source (no API key required)
    res = requests.get(
        "https://www.axiomoverwatch.io/api/v1/ais/any/9876543/location/latest"
    )
    fix = res.json()  # JSON-LD GeoCoordinates payload
    ```
  

  
    ```js Node
    // Freshest position across any source (no API key required)
    const fix = await fetch(
      "https://www.axiomoverwatch.io/api/v1/ais/any/9876543/location/latest"
    ).then((r) => r.json()); // JSON-LD GeoCoordinates payload
    ```
  



# Watchlists (/overwatch/api/watchlist)



Track vessels you care about and get notified when key events occur. Vessels on your watchlist are highlighted across alerts, positions, and risk views.

## `GET` `/api/v1/watchlist` [#get-apiv1watchlist]


  Requires API key.


List all vessels on your watchlist, including joined vessel details.

**Response**

```json
{
  "watchlist": [
    {
      "id": 1,
      "imo_number": "9622629",
      "label": "Meridian — Gulf fleet",
      "notify_on": ["port_entry", "port_departure", "dark_event", "sanctions_match"],
      "created_at": "2026-04-18T12:00:00Z",
      "vessels": {
        "name": "MV Meridian",
        "vessel_type": "Bulk Carrier",
        "flag": "MH",
        "risk_score": 42,
        "risk_tier": "medium"
      }
    }
  ],
  "count": 1,
  "tier": "pro"
}
```

Each `watchlist` entry carries `id`, `imo_number`, `label`, `notify_on`, `created_at`, and a joined `vessels` object with `name`, `vessel_type`, `flag`, `risk_score`, `risk_tier`.

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/watchlist
```

## `POST` `/api/v1/watchlist` [#post-apiv1watchlist]


  Requires API key.


Add a vessel to your watchlist. If the vessel is already watched, the existing entry is updated.

**Parameters**

| Name         | Type      | Required | Description                              |
| ------------ | --------- | -------- | ---------------------------------------- |
| `imo_number` | string    | ✓        | 7-digit IMO number                       |
| `label`      | string    |          | Custom display label                     |
| `notify_on`  | string\[] |          | Event types to alert on (defaults below) |


  `category_id`

   is not supported. The live schema has no 

  `vessel_watchlist.category_id`

   column — including 

  `category_id`

   in the request body (even 

  `null`

  ) returns 

  `503`

   before any other validation runs. 

  `sort_order`

   is likewise read by no code path here and silently has no effect.


**Default `notify_on` events**

| Event             | Description                           |
| ----------------- | ------------------------------------- |
| `port_entry`      | Vessel arrives at any monitored port  |
| `port_departure`  | Vessel departs a monitored port       |
| `dark_event`      | AIS signal gap detected               |
| `sanctions_match` | Vessel flagged by sanctions screening |

**Response**

```json
{
  "watchlist_entry": {},
  "message": "Watching vessel 9622629"
}
```

`watchlist_entry` returns the full `vessel_watchlist` row — the handler calls `.select()` with no column list after the upsert.

**Errors**

| Status | When                                            |
| ------ | ----------------------------------------------- |
| `400`  | Body is not valid JSON                          |
| `400`  | `imo_number` missing or empty                   |
| `400`  | `notify_on` present but not an array of strings |
| `503`  | `category_id` present in the request body       |
| `500`  | Internal server error                           |

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist \
  -d '{
    "imo_number": "9622629",
    "label": "Meridian — Gulf fleet",
    "notify_on": ["port_entry", "dark_event", "sanctions_match"]
  }'
```

## `PATCH` `/api/v1/watchlist` [#patch-apiv1watchlist]


  Requires API key.


Update a watched vessel's label or notification events.

**Parameters**

| Name         | Type      | Required | Description                        |
| ------------ | --------- | -------- | ---------------------------------- |
| `imo_number` | string    | ✓        | IMO number of the vessel to update |
| `label`      | string    |          | New label                          |
| `notify_on`  | string\[] |          | Updated event list                 |


  `category_id`

   is not supported — including it in the request body (even 

  `null`

  ) returns 

  `503`

  . 

  `sort_order`

   is likewise read by no code path here and silently has no effect.


**Response**

```json
{
  "watchlist_entry": {},
  "message": "Updated 9622629"
}
```

`watchlist_entry` returns the full `vessel_watchlist` row — the handler calls `.select()` with no column list after the update.

**Errors**

| Status | When                                                           |
| ------ | -------------------------------------------------------------- |
| `400`  | Body is not valid JSON                                         |
| `400`  | `imo_number` missing or empty                                  |
| `400`  | `notify_on` present but not an array of strings                |
| `400`  | Neither `label` nor `notify_on` provided (no fields to update) |
| `503`  | `category_id` present in the request body                      |
| `500`  | Internal server error                                          |

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist \
  -d '{"imo_number": "9622629", "notify_on": ["dark_event"]}'
```

## `DELETE` `/api/v1/watchlist` [#delete-apiv1watchlist]


  Requires API key.


Remove a vessel from your watchlist.

**Parameters**

| Name  | Type   | Required | Description              |
| ----- | ------ | -------- | ------------------------ |
| `imo` | string | ✓        | IMO number (query param) |

**Response**

```json
{ "message": "Removed 9622629 from watchlist" }
```

**Errors**

| Status | When                      |
| ------ | ------------------------- |
| `400`  | `imo` query param missing |
| `500`  | Internal server error     |

**Example**

```bash
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/watchlist?imo=9622629"
```

***

## Categories [#categories]


  Not implemented. Every method below always returns 

  `503`

   — the live schema has no 

  `watchlist_categories`

   table or 

  `vessel_watchlist.category_id`

   column. Documented here for visibility only; do not build against these shapes.


Category support (nesting, `default_notify_on` propagation) was never shipped for this launch.

### `GET` `/api/v1/watchlist/categories` [#get-apiv1watchlistcategories]


  Requires API key.


Always returns `503` regardless of input.

**Response**

```json
{ "error": "Watchlist categories are not launch-supported" }
```

**Example**

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.axiomoverwatch.io/api/v1/watchlist/categories
```

### `POST` `/api/v1/watchlist/categories` [#post-apiv1watchlistcategories]


  Requires API key.


Always returns `503` regardless of input.

**Response**

```json
{ "error": "Watchlist categories are not launch-supported" }
```

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist/categories \
  -d '{"name": "Gulf fleet", "default_notify_on": ["dark_event", "sanctions_match"]}'
```

### `PATCH` `/api/v1/watchlist/categories` [#patch-apiv1watchlistcategories]


  Requires API key.


Always returns `503` regardless of input.

**Response**

```json
{ "error": "Watchlist categories are not launch-supported" }
```

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist/categories \
  -d '{"id": 5, "name": "Gulf fleet — priority"}'
```

### `DELETE` `/api/v1/watchlist/categories` [#delete-apiv1watchlistcategories]


  Requires API key.


Always returns `503` regardless of input.

**Response**

```json
{ "error": "Watchlist categories are not launch-supported" }
```

**Example**

```bash
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://www.axiomoverwatch.io/api/v1/watchlist/categories?id=5"
```

***

## Bulk operations [#bulk-operations]

Add or modify up to 100 vessels at once.

### `POST` `/api/v1/watchlist/bulk` [#post-apiv1watchlistbulk]


  Requires API key.


Add multiple vessels in a single request.

**Parameters**

| Name        | Type      | Required | Description                                                                                                          |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `imos`      | string\[] | ✓        | IMO numbers to add — array of strings, or a single comma/whitespace-separated string; deduplicated and capped at 100 |
| `label`     | string    |          | Label applied to all vessels                                                                                         |
| `notify_on` | string\[] |          | Event types for all vessels (defaults to the standard list above if omitted)                                         |


  `category_id`

   is not supported — including it in the request body (even 

  `null`

  ) returns 

  `503`

  .


**Response**

```json
{
  "added": 0,
  "imos": 0,
  "watchlist_entries": []
}
```

Each `watchlist_entries` entry carries `id`, `imo_number`, `notify_on`.

**Errors**

| Status | When                                                 |
| ------ | ---------------------------------------------------- |
| `400`  | Body is not valid JSON                               |
| `400`  | No usable IMOs after parsing (`imos` empty, max 100) |
| `400`  | `notify_on` present but not an array of strings      |
| `503`  | `category_id` present in the request body            |
| `500`  | Internal server error                                |

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist/bulk \
  -d '{
    "imos": ["9622629", "9622630", "9622631"],
    "notify_on": ["dark_event", "sanctions_match"]
  }'
```

### `PATCH` `/api/v1/watchlist/bulk` [#patch-apiv1watchlistbulk]


  Requires API key.


Perform a bulk action on multiple watched vessels.

**Parameters**

| Name        | Type      | Required | Description                               |
| ----------- | --------- | -------- | ----------------------------------------- |
| `imos`      | string\[] | ✓        | Array of IMO numbers (max 100)            |
| `action`    | string    | ✓        | `remove`, `set_notify_on`, or `set_label` |
| `notify_on` | string\[] |          | Required for `set_notify_on`              |
| `label`     | string    |          | Required for `set_label`                  |


  `set_category`

   and 

  `category_id`

   are not supported — either one in the request returns 

  `503`

  .


**Response**

```json
{
  "success": true,
  "affected": 0,
  "watchlist_entries": []
}
```

`action: "remove"` responses omit `watchlist_entries`. For `set_notify_on` / `set_label`, each `watchlist_entries` entry carries `id`, `imo_number`, `notify_on`, `label`.

**Errors**

| Status | When                                                            |
| ------ | --------------------------------------------------------------- |
| `400`  | Body is not valid JSON                                          |
| `400`  | No usable IMOs after parsing (`imos` empty, max 100)            |
| `400`  | `action` is not one of `remove` / `set_notify_on` / `set_label` |
| `400`  | `notify_on` missing or invalid for `set_notify_on`              |
| `503`  | `category_id` present, or `action` is `set_category`            |
| `500`  | Internal server error                                           |

**Example**

```bash
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/watchlist/bulk \
  -d '{
    "imos": ["9622629", "9622630"],
    "action": "set_notify_on",
    "notify_on": ["dark_event"]
  }'
```


# Webhooks (/overwatch/api/webhooks)



Subscribe to real-time event notifications.

## `GET` `/api/v1/webhooks` [#get-apiv1webhooks]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


List your registered webhooks.

**Response**

```json
{ "webhooks": [] }
```

Each `webhooks` entry carries `id`, `name`, `url`, `events`, `enabled`, `last_triggered_at`, `created_at` (the `secret` is intentionally excluded).

**Example**

```bash
curl -X GET -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/webhooks
```

## `POST` `/api/v1/webhooks` [#post-apiv1webhooks]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Register a new webhook endpoint. Must be HTTPS.

**Parameters**

| Name     | Type           | Required | Description                                                                                                           |
| -------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `name`   | string         | ✓        | Webhook name                                                                                                          |
| `url`    | string         | ✓        | Must use `https:`, must not include embedded credentials, and must not point to an internal/private/localhost address |
| `events` | array\ |          | Default `["anomaly"]`                                                                                                 |

**Response** (`201`)

```json
{ "webhook": {} }
```

The `webhook` object carries `id`, `name`, `url`, `events`, `enabled`, `created_at`.

**Errors**

* `400` — `name` and `url` are required
* `400` — `url` fails validation (not HTTPS, contains credentials, or points to an internal/private address)
* `500` — internal server error

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/webhooks \
  -d '{"name":"value","url":"https://example.com/hook","events":["anomaly"]}'
```

## `POST` `/api/v1/webhooks/slack-test` [#post-apiv1webhooksslack-test]


  Requires 

  [admin authorization](/overwatch/api/admin-auth)

  .


Send a test notification to a Slack webhook URL.

**Parameters**

| Name  | Type   | Required | Description                              |
| ----- | ------ | -------- | ---------------------------------------- |
| `url` | string | ✓        | A `hooks.slack.com` incoming webhook URL |

**Response**

```json
{
  "success": true,
  "message": "Test message sent to Slack"
}
```

**Errors**

* `400` — missing/invalid request body, missing `url`, or `url` isn't a `hooks.slack.com` URL
* `502` — Slack responded with a non-2xx status
* `504` — request to Slack timed out (5s)
* `500` — failed to reach the Slack webhook

**Example**

```bash
curl -X POST -H "X-API-Key: YOUR_ADMIN_MACHINE_KEY" \
  https://www.axiomoverwatch.io/api/v1/webhooks/slack-test \
  -d '{"url":"https://hooks.slack.com/services/VALUE"}'
```


# Cargo validation methodology (/overwatch/methodology/cargo-validation)



Axiom Overwatch publishes weekly cargo volume estimates by port. This page explains how those numbers are produced and the validation paths that keep them grounded in reality.

## The inference chain [#the-inference-chain]

For each vessel arriving at or departing from a monitored port:




  
    ### Identity + dimensions [#identity--dimensions]

    AIS message identifies the vessel by IMO. We look up its registered DWT, length, beam, and design draft from the global vessel registry.
  

  
    ### Operational draft [#operational-draft]

    The AIS Type-5 (static report) and Type-1/3 (position) messages include the vessel's current draft, broadcast by the captain. Differences between design draft and operational draft tell us whether the vessel is loading, unloading, or in ballast.
  

  
    ### Cargo per voyage [#cargo-per-voyage]

    Tonnage carried = `f(DWT, draft, hull form)` using a hydrostatic curve appropriate for the vessel type (bulker, tanker, container). For bulkers, this is well-modeled with TPC (tonnes per centimetre).

    When a vessel has a hydrostatic profile on file, Overwatch uses the full displacement table and trim model to produce a higher-confidence estimate. Water density at the port is factored in when available. Vessels without a profile fall back to the standard DWT-based approximation.
  

  
    ### Aggregate per port per week [#aggregate-per-port-per-week]

    Sum across all departures for the week. Adjust for vessel-type-specific calibration factors derived from historical USDA actuals.
  


## What we validate against [#what-we-validate-against]

| Source                               | Frequency         | What it confirms                                                                                         |
| ------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------- |
| **USDA Grain Transportation Report** | Weekly            | Grain volumes at US ports (corn, wheat, soy)                                                             |
| **EIA petroleum data**               | Weekly            | Crude oil and refined product flows                                                                      |
| **Port authority statistics**        | Monthly–quarterly | Total throughput by port                                                                                 |
| **UN Comtrade**                      | Monthly           | Bilateral trade flows for cross-check                                                                    |
| **Mirror data**                      | Annual            | Exporter-reported vs importer-reported volumes — large gaps signal misclassification or trade re-routing |

When our estimates diverge from authoritative sources by more than the tier-specific tolerance, the affected port is flagged in `/api/v1/anomalies/maturity` and a banner appears on the port detail page.

## Confidence tiers [#confidence-tiers]

Every estimate carries a confidence tier:

* **High** — historical agreement with authoritative data within ±5%
* **Medium** — within ±15%, or limited authoritative data available
* **Low** — within ±30%, or recent calibration changes
* **Indicative** — port is too new to validate against history; numbers are model-only

## Hydrostatic estimation [#hydrostatic-estimation]

For vessels with a hydrostatic profile, Overwatch uses a multi-factor estimation path that produces more accurate cargo figures than the standard DWT-based method:

1. **Displacement table lookup** — the vessel's hydrostatic rows map draft readings to displacement tonnage, accounting for hull geometry.
2. **Trim correction** — a trim model adjusts the estimate for the difference between fore and aft drafts at arrival and departure.
3. **Water density adjustment** — local water density measurements at the port correct for the difference between freshwater and saltwater displacement.

The API exposes the estimation method and confidence score for each visit through the `hydrostatic_method`, `hydrostatic_confidence`, and `hydrostatic_confidence_score` fields on vessel visit records. See the [estimates API](/overwatch/api/estimates) for details.

### Water density sources [#water-density-sources]

Each port's surface water density is refreshed monthly and used directly in the displacement step above. The ingestion picks the most accurate source available per port:

| Tier | Source                                                            | Coverage                                                                                                                   | Notes                                                                                                                                                                                                                                                                                                                        |
| ---- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | NOAA CO-OPS real-time water temperature + climatological salinity | US ports with a confirmed CO-OPS temperature gauge (New Orleans, Houston, Baltimore, Norfolk, Los Angeles)                 | Live temperature from a station inside the port approach paired with the regional climatological salinity for that water body. CO-OPS does not publish reliable real-time salinity at most open-ocean and Gulf stations, so salinity is always climatological.                                                               |
| 2    | Published climatological constants — slug override                | Ports in unusual water bodies (Yamal/Arctic, Persian Gulf interior, Strait of Hormuz, Red Sea, Black Sea, English Channel) | Hand-tuned T/S for enclosed seas, Arctic ports, and high-salinity basins where a country-level mean would be misleading.                                                                                                                                                                                                     |
| 3    | Published climatological constants — country                      | All other ports globally                                                                                                   | Per-country regional means derived from WOA23 published surface climatology and NOAA Atlas 14. Currently covers USA, Brazil, Australia, Russia, Qatar, South Africa, the UAE, Iran, Saudi Arabia, Singapore, China, Oman, the Netherlands, Germany, Belgium, France, and Romania, with a global default for everything else. |

Density is computed from the resulting temperature and salinity using the **UNESCO-80** seawater equation of state at surface pressure. Each refreshed reading is stored per port at H3 resolution 8 along with its source identifier (`noaa_coops:+climato_sal` or `climato:`), so cargo estimates remain reproducible against the exact water density value that was used at the time.

The pipeline runs on the 1st of each month at 03:30 UTC, and rows older than 90 days are pruned automatically. Water density only changes meaningfully on a seasonal cycle, so a monthly refresh is sufficient for hydrostatic accuracy without introducing churn into historical estimates.


  Historical vessel visits are periodically re-estimated as new hydrostatic profiles become available. If you notice cargo figures change for past visits, this is expected — the re-estimation improves accuracy for vessels that previously lacked profile data.


## What the model doesn't see [#what-the-model-doesnt-see]

* **Ship-to-ship transfers** in international waters before arrival (we detect these separately under `/api/v1/risk/sts`, but they reduce arrival-port volume estimates).
* **Captain-falsified draft** declarations on AIS. We surface anomalies via `/api/v1/risk/mismatches`.
* **Container cargo** value — we estimate TEU counts, not invoice value.
* **Bagged cargo** in general-cargo vessels — TPC is less precise than bulk.

## Cross-checks built into the API [#cross-checks-built-into-the-api]

* `/api/v1/anomalies` — surfaces seasonal and trailing anomalies in the export volumes
* `/api/v1/anomalies/maturity` — per-port data sufficiency scores
* `/api/v1/calibration` — current calibration factors per vessel type
* `/api/v1/forecasts/accuracy` — MAE / MAPE / directional accuracy of forecasts vs actuals

If you're using Overwatch numbers in regulated reporting (commodity trading, ESG disclosure), pull the calibration + accuracy data alongside the estimates — it shows your auditor we're not hiding the residuals.


# Chokepoint transits (/overwatch/methodology/chokepoint-transits)



Axiom Overwatch uses AIS positions and corridor geometry to analyze vessel movement through four maritime chokepoints: **Bab-el-Mandeb**, the **Strait of Hormuz**, the **southern Suez approaches**, and **Cape Agulhas**.

The supported confirmation posture is AIS-only. Overwatch can also query the Copernicus Sentinel-1 catalog to learn whether radar imagery may exist near a place and time, but a catalog result does not identify a vessel, process image pixels, or confirm a transit.


  Do not treat SAR catalog coverage as evidence that a vessel crossed a corridor. Pixel detection and AIS-to-SAR confirmation are not part of the supported production workflow.


## When to use this [#when-to-use-this]

Use chokepoint analysis to:

* Review AIS-observed approaches and passages through a named corridor.
* Compare a vessel's projected route with later AIS positions.
* Investigate stale or missing AIS while keeping the evidentiary gap explicit.
* Check whether Sentinel-1 products may exist for an independent imagery workflow.

For vessel-level routing without corridor semantics, use [Route forecasts](/overwatch/methodology/route-forecasts). For catalog availability near one location and time, use the [SAR coverage API](/overwatch/api/sar-coverage).

## Current operating boundary [#current-operating-boundary]

| Capability                             | Current documentation contract                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| AIS position and route evidence        | Supported. Use observed positions and route forecasts to reason about a vessel's movement.                      |
| Chokepoint corridor geometry           | Supported for the four configured corridors on this page.                                                       |
| AIS-based transit conclusion           | Supported when the conclusion is backed by AIS evidence.                                                        |
| Sentinel-1 catalog lookup              | Supported through the authenticated SAR coverage endpoint. It reports product availability and timing metadata. |
| Radar pixel detection                  | Not a supported production capability.                                                                          |
| Automatic AIS-to-SAR vessel match      | Not a supported production capability.                                                                          |
| SAR-confirmed or SAR-only dark transit | Do not claim from the current product surface.                                                                  |



## The chokepoints [#the-chokepoints]

| Corridor key    | Name                                     | Analytical boundary                                                                                    |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `bab-el-mandeb` | Bab-el-Mandeb / Red Sea South            | Strait between Yemen and Djibouti, connecting the Gulf of Aden and Red Sea.                            |
| `hormuz`        | Strait of Hormuz / Northern Gulf         | Passage between the Persian Gulf and Gulf of Oman.                                                     |
| `suez-s`        | Southern Suez approaches / Red Sea North | Southern approach to the canal; surface analysis does not imply coverage inside the land-locked canal. |
| `cape-agulhas`  | Cape Agulhas / Southern Africa           | Atlantic–Indian Ocean rounding corridor used for detour analysis.                                      |

Each corridor has an analysis polygon plus approach and exit geometry. A projected path can indicate that a vessel is likely to enter a corridor; later AIS positions provide the evidence for whether the vessel was observed continuing through it.

## AIS analysis workflow [#ais-analysis-workflow]


  
    ### Start with recent AIS [#start-with-recent-ais]

    Confirm that the vessel has a recent position, course, and speed. A stale, stationary, or heading-less position cannot support a reliable forward projection.
  

  
    ### Project the route [#project-the-route]

    Use the vessel's latest AIS state and [route forecast](/overwatch/methodology/route-forecasts) to evaluate whether its path intersects a configured chokepoint.
  

  
    ### Watch for observed positions [#watch-for-observed-positions]

    Compare the projected approach with later AIS positions in or beyond the corridor. Keep the projection and observation timestamps separate.
  

  
    ### State the evidence [#state-the-evidence]

    Describe an observed transit only when AIS supports it. If the vessel stops reporting, record an AIS gap rather than upgrading the gap to a radar-confirmed or dark transit.
  


## Using Sentinel-1 catalog coverage [#using-sentinel-1-catalog-coverage]

The [SAR coverage endpoint](/overwatch/api/sar-coverage) accepts a location, time, and radius, then queries the Copernicus catalog for matching Sentinel-1 products. Its response can answer questions such as:

* Did the catalog return a product near this place and time?
* When was the closest cataloged pass?
* Is the product listed as online?
* How strong is the timing-and-coverage potential for a separate investigation?

It cannot answer:

* Which vessel appears in an image.
* Whether any ship-like pixel exists.
* Whether a cataloged product was downloaded or processed.
* Whether an AIS gap is a sanctions-evasion event.
* Whether a vessel completed a chokepoint transit.


  The repository contains readiness-oriented SAR code and data structures, including a default-disabled monitor and an unavailable detector scaffold. Their presence is not launch evidence. Re-verify feature configuration, processing, and reviewed precision evidence before documenting any future SAR confirmation capability.


## Interpret missing AIS carefully [#interpret-missing-ais-carefully]

An AIS gap is an absence of expected position reports, not proof of concealment. Weather, terrestrial receiver coverage, equipment state, congestion, and operational behavior can all affect reporting.

When the evidence is incomplete:

1. Preserve the last observed AIS position and timestamp.
2. Keep route projections labeled as projections.
3. Use other Overwatch signals as corroborating context, not as a substitute observation.
4. Treat catalog coverage as a pointer for independent imagery analysis.
5. Avoid assigning a vessel identity to radar imagery without a separately validated detection and matching workflow.

Continue with [AIS coverage](/overwatch/ais-coverage), [Route forecasts](/overwatch/methodology/route-forecasts), and the [SAR coverage API](/overwatch/api/sar-coverage).


# Course alteration anomalies (/overwatch/methodology/course-alteration-anomalies)



The AIS ingestion worker continuously evaluates each underway vessel's heading against its recent course history. When the current course deviates sharply from a vessel's circular-mean heading over the prior 6 hours — and the vessel is not maneuvering near a port — Overwatch emits a `course_alteration` row into the `axiom_events` table. These events surface unexpected mid-voyage turns that often correlate with rendezvous behavior, sanctions evasion, dark-fleet activity, or operational disruption.

## When to use this [#when-to-use-this]

* Investigate vessels making unexplained turns away from their declared destination
* Build watchlist signals that flag mid-voyage rendezvous candidates
* Cross-reference course changes with [STS encounters](/overwatch/api/risk), [dark events](/overwatch/api/risk), or [sanctions matches](/overwatch/api/sanctions)
* Power custom [alert rules](/overwatch/api/alerts) that route significant maneuvers to Slack, Teams, email, or webhooks

If you only need aggregate dark-fleet or risk-tier views, the [Risk Intelligence](/overwatch/api/risk) endpoints are the right entry point. Use this event stream when you need granular, per-fix course-change signals.

## Detection criteria [#detection-criteria]

A `course_alteration` event is emitted only when **all** of the following conditions are met on a new AIS position fix:



| Criterion            | Threshold                                          | Rationale                                                                                         |
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Vessel is underway   | speed > 0.5 knots                                  | Stationary vessels (drifting, anchored) are excluded — their heading is noisy and not meaningful. |
| Prior heading buffer | ≥ 5 fixes in the last 6 hours                      | Short windows produce unreliable circular means.                                                  |
| Coverage duration    | ≥ 30 minutes between oldest fix and current fix    | Suppresses false positives from rapid bursts of fixes.                                            |
| Course deviation     | ≥ 45° from the 6-hour circular mean                | The signed shortest angular distance — wraps correctly across 0°/360°.                            |
| Distance from port   | > 10 km from any `port_zones` polygon              | Port maneuvering produces legitimate sharp turns we don't want flooding the feed.                 |
| Per-vessel dedup     | No prior emit in the last 6 hours for the same IMO | Prevents repeated alerts on a sustained turn.                                                     |

The 6-hour heading window uses a **circular mean** rather than an arithmetic mean so that compass wraparound is handled correctly. An arithmetic mean of `[359°, 1°]` yields 180° (wrong); the circular mean yields 0° (correct).

## Event shape [#event-shape]

Each detection writes a single row to `axiom_events`:

```json
{
  "entity_id": "9622629",
  "entity_type": "vessel",
  "event_type": "course_alteration",
  "event_category": "kinematic_anomaly",
  "started_at": "2026-04-28T14:32:11Z",
  "magnitude": 87.4,
  "confidence": 0.7,
  "source": "aisstream-worker",
  "product": "overwatch",
  "metadata": {
    "delta_deg": -87.4,
    "median_heading_deg": 92.1,
    "current_heading_deg": 4.7,
    "current_speed_knots": 12.3,
    "fix_count": 38,
    "coverage_minutes": 312,
    "latitude": 12.4,
    "longitude": 43.8
  }
}
```

| Field                          | Description                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `entity_id`                    | 7-digit IMO number of the vessel that altered course.                                          |
| `event_type`                   | Always `course_alteration`.                                                                    |
| `event_category`               | Always `kinematic_anomaly` — useful for grouping with future kinematic detectors.              |
| `started_at`                   | Timestamp of the AIS fix that triggered the detection.                                         |
| `magnitude`                    | Absolute course deviation in degrees (always positive).                                        |
| `metadata.delta_deg`           | Signed deviation in `(-180, 180]`. Negative is a port-side (left) turn, positive is starboard. |
| `metadata.median_heading_deg`  | Circular mean of the prior 6-hour heading buffer, in `[0, 360)`.                               |
| `metadata.current_heading_deg` | Vessel's heading at the moment of detection.                                                   |
| `metadata.fix_count`           | Number of fixes in the prior buffer used to compute the median.                                |
| `metadata.coverage_minutes`    | Span between the oldest buffered fix and the current fix.                                      |

Events are idempotent on `(entity_id, started_at, event_type)` — duplicate inserts are silently swallowed.

## Querying [#querying]

The `axiom_events` table is indexed for `(event_type, started_at DESC)` and `(entity_id, event_type, started_at DESC)`.

```sql
-- All course-alteration events in the last 24 hours, largest turns first.
select
  entity_id as imo_number,
  started_at,
  magnitude as turn_deg,
  metadata->>'median_heading_deg' as prior_heading,
  metadata->>'current_heading_deg' as new_heading,
  metadata->>'latitude' as lat,
  metadata->>'longitude' as lon
from axiom_events
where event_type = 'course_alteration'
  and started_at >= now() - interval '24 hours'
order by magnitude desc;
```

```sql
-- Course alterations for a watched vessel, joined with its current
-- risk profile.
select ae.started_at, ae.magnitude, ae.metadata, v.name, v.flag, v.risk_tier
from axiom_events ae
join vessels v on v.imo_number = ae.entity_id
where ae.event_type = 'course_alteration'
  and ae.entity_id = $1
order by ae.started_at desc
limit 50;
```

```sql
-- Course alterations clustered with STS or dark events on the same
-- vessel within a 24h window — a stronger signal than any one detector.
with course_events as (
  select entity_id, started_at
  from axiom_events
  where event_type = 'course_alteration'
    and started_at >= now() - interval '7 days'
)
select c.entity_id, c.started_at, count(distinct ae.event_type) as concurrent_signals
from course_events c
join axiom_events ae
  on ae.entity_id = c.entity_id
 and ae.started_at between c.started_at - interval '12 hours'
                      and c.started_at + interval '12 hours'
 and ae.event_type in ('sts_encounter', 'dark_event', 'identity_change')
group by c.entity_id, c.started_at
having count(distinct ae.event_type) >= 1
order by concurrent_signals desc, c.started_at desc;
```

## Routing to alerts [#routing-to-alerts]

Course alterations flow into the [unified alert inbox](/overwatch/api/alerts) automatically. To get notified for turns that match specific criteria — for example, large turns by watchlisted vessels, or any turn near a known STS hotspot — create an alert rule against the `event_type` field:

```bash
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://www.axiomoverwatch.io/api/v1/alerts/rules \
  -d '{
    "name": "Sharp turn on watched vessel",
    "expression": {
      "kind": "group",
      "operator": "and",
      "conditions": [
        { "kind": "condition", "field": "event_type", "op": "eq", "value": "course_alteration" },
        { "kind": "condition", "field": "magnitude", "op": "gte", "value": 90 }
      ]
    },
    "dedupe_window_minutes": 360
  }'
```

## Tuning notes [#tuning-notes]

The detector ships with conservative defaults that prioritize precision over recall:

* **45° threshold** filters out minor course corrections common in transit traffic. Routine sea-keeping rarely produces sustained 45°+ deviations from a 6-hour mean.
* **6-hour window** smooths over short-term zigzag patterns (weather avoidance, traffic separation schemes) while remaining responsive enough to catch genuine maneuvers.
* **10 km port buffer** uses a GIST-indexed `geography` `ST_DWithin` check against the `port_zones` table, so the per-fix overhead is negligible.
* **6-hour per-IMO dedup window** prevents a sustained heading change from producing repeated events as the buffer slowly catches up.

Tuning is currently a code-level change; if you need different thresholds for a specific deployment, contact [support](mailto:support@axiomancer.io).


  Course alteration is purely kinematic — it does not cross-check the vessel's declared destination, AIS nav status, or weather routing data. Treat it as a high-precision flag for "look harder at this voyage", not a standalone classification of intent.



# Pairwise encounter extraction (/overwatch/methodology/encounter-extraction)



Axiom Overwatch derives vessel-to-vessel encounters from raw AIS positions and emits per-pair, per-timestep geometry — closest point of approach (CPA), time to CPA (TCPA), range, closing speed, and bearing rate. These records are the foundation Overwatch uses for collision-risk surfacing, ship-to-ship rendezvous detection, and forensic incident reconstruction.

## When to use it [#when-to-use-it]

Reach for encounter data when you need to answer questions about how two vessels behaved relative to each other, not how one vessel behaved at a point in time. Typical use cases:

* Reviewing near-miss geometry around a port approach or a traffic separation scheme
* Reconstructing the timeline of a collision, allision, or grounding for a forensics report
* Triggering downstream risk scoring (COLREGS, kinematic causality)
* Filtering for candidate ship-to-ship transfer windows before deeper investigation

If you only need single-vessel state — speed, heading, draft, port arrivals — use [vessel positions](/overwatch/api/vessels) instead.

## How encounters are detected [#how-encounters-are-detected]

For every pair of vessels in a spatial/temporal window, Overwatch streams their AIS positions through a hysteresis trigger. An encounter opens when the geometry crosses the entry threshold and closes after the exit threshold has held for a sustained window.




  
    ### Stream-merge per pair [#stream-merge-per-pair]

    For each unordered vessel pair, positions from both vessels are merged in time order. Every input timestamp triggers re-evaluation against the most recent fix from the other vessel — there is no interpolation between AIS reports, so observed geometry is always grounded in real broadcasts.
  

  
    ### Geometry per epoch [#geometry-per-epoch]

    At each evaluation tick, Overwatch computes range (nautical miles), relative bearings from each vessel, course difference, closing speed (knots), TCPA (seconds), DCPA (nautical miles), bearing rate (degrees per minute), and the pass side from each vessel's perspective.
  

  
    ### Hysteresis trigger [#hysteresis-trigger]

    A deterministic risk probability `risk_prob` is derived from range, TCPA, and DCPA factors. The encounter opens when `risk_prob` rises above the entry threshold and the geometric gates (range, TCPA, DCPA) are simultaneously inside their limits. It closes only after `risk_prob` has stayed below the exit threshold for the configured hysteresis window.
  

  
    ### Canonical pair ordering [#canonical-pair-ordering]

    Each unordered vessel pair is stored once, with `vessel_a_id < vessel_b_id` (lexicographic on IMO). This guarantees a single canonical row per encounter and avoids double-counting when querying by either vessel.
  


## Default thresholds [#default-thresholds]

| Parameter        | Default | Meaning                                                         |
| ---------------- | ------- | --------------------------------------------------------------- |
| `range_max_nm`   | 6.0     | Maximum range, in nautical miles, for the geometry gate         |
| `tcpa_max_s`     | 1800    | Maximum TCPA, in seconds (30 minutes)                           |
| `dcpa_max_nm`    | 1.5     | Maximum projected DCPA, in nautical miles                       |
| `p_risk_enter`   | 0.35    | `risk_prob` required to open an encounter                       |
| `p_risk_exit`    | 0.20    | `risk_prob` required (sustained) to close one                   |
| `hysteresis_s`   | 300     | Seconds the exit condition must hold (5 minutes)                |
| `pair_max_age_s` | 600     | Discard pairs whose latest fixes are more than 10 minutes apart |

These defaults work for open-water and approach geometry. Restricted waters or chokepoint contexts may justify tighter values; pass overrides at extraction time.

## Output shape [#output-shape]

Two records are produced per detected encounter.

**Encounter** (one row per detected window):

* `vessel_a_id`, `vessel_b_id` — canonical IMO ordering, `vessel_a_id < vessel_b_id`
* `start_ts`, `end_ts`, `cpa_ts` — encounter window and the timestamp of minimum range
* `min_range_nm`, `min_dcpa_nm`, `min_tcpa_s` — geometry minima across the window
* `risk_window_start_ts` — the first epoch where `risk_prob` crossed the entry threshold
* `observed_fraction` — fraction of epochs grounded in direct AIS observation (always `1.0` today; reserved for future imputation)
* `encounter_conf` — mean per-epoch geometry confidence
* `context_tag` — environmental context (`open_sea`, `channel`, `tss`, `approach`, `anchorage`); populated by a downstream classifier
* `max_course_change_a_deg`, `max_course_change_b_deg` — largest single-step COG delta observed for each vessel across the encounter, in degrees
* `rule17_deviation_a`, `rule17_deviation_b` — boolean flags fired when the corresponding vessel's mean stand-on probability across the encounter clears a threshold AND its max course change is large enough to count as a meaningful maneuver (see [Rule 17 deviation detection](#rule-17-deviation-detection))
* `rule17_handoff_ts`, `rule17_handoff_trigger` — the timestamp at which Rule 17(a) "keep course and speed" authority transitioned into Rule 17(b)/(c) "may / must take avoiding action," and which gate fired (`giveway_inaction` or `extremis`). Both are `NULL` when no handoff condition tripped (see [Rule 17 handoff timestamp](#rule-17-handoff-timestamp))

**Encounter epoch** (one row per timestep, keyed by `encounter_id` + `ts_utc`):

* `range_nm`, `rel_bearing_a_deg`, `rel_bearing_b_deg`, `course_diff_deg`
* `closing_speed_kt`, `tcpa_s`, `dcpa_nm`, `bearing_rate_deg_min`
* `pass_side_a`, `pass_side_b` — `-1` (port), `0` (ahead/astern), `1` (starboard)
* `risk_prob` — deterministic geometry-only risk in `[0, 1]`
* `p_head_on`, `p_overtaking`, `p_crossing` — COLREGS rule posteriors derived from epoch geometry; sum to `1`
* `p_special_context` — reserved for TSS / narrow-channel / RAM context; left `NULL` until spatial context ingestion lands
* `give_way_prob_a`, `stand_on_prob_a`, `give_way_prob_b`, `stand_on_prob_b` — per-vessel role posteriors conditioned on the rule posteriors

## Configuring an extraction [#configuring-an-extraction]

The extractor is exposed from `@axiom/core` for use in workers and Edge Functions. Pass a pre-filtered slice of AIS positions for a tractable spatial/temporal window — the multi-vessel form is `O(n²)` in the number of unique IMOs.

```ts
import { extractEncounters } from "@axiom/core/processing/encounter-extraction"

const encounters = extractEncounters(positions, {
  rangeMaxNm:  3.0,    // tighter than default for a port approach
  tcpaMaxS:    1200,
  dcpaMaxNm:   1.0,
  pRiskEnter:  0.40,
  pRiskExit:   0.20,
  hysteresisS: 300,
  pairMaxAgeS: 600,
})

for (const enc of encounters) {
  console.log(
    enc.vesselAId, "x", enc.vesselBId,
    "min range", enc.minRangeNm.toFixed(2), "nm",
    "min DCPA", enc.minDcpaNm.toFixed(2), "nm",
    "epochs", enc.epochs.length,
  )
}
```

For a single known pair, use `extractEncountersForPair(vesselA, vesselB, posA, posB, config)` — `vesselA` must sort lexicographically before `vesselB`.

## Production pipeline [#production-pipeline]

In production, the extractor runs as a scheduled Edge Function rather than ad-hoc against `@axiom/core`. The function reads recent AIS positions, generates candidate vessel pairs with H3 spatial indexing, runs the same algorithm above, and persists results. Output is the source of truth for the [Risk API](/overwatch/api/risk), the [Investigations API](/overwatch/api/investigations), and any downstream COLREGS / kinematic-causality pipelines.

### Hourly schedule [#hourly-schedule]

The `extract-encounters-hourly` cron job invokes the Edge Function at minute `:07` of every hour. Each run pulls the trailing 90 minutes of AIS positions — a 30-minute overlap with the prior run guarantees encounters that straddle the hour boundary are seen end-to-end.

Results are persisted with two upserts:

* `pairwise_encounter` keyed on `(vessel_a_id, vessel_b_id, start_ts)`
* `encounter_epoch` keyed on `(encounter_id, ts_utc)`

Because both keys are stable across runs, re-invoking the function over the same window is idempotent — a re-run updates the existing rows instead of inserting duplicates.

### Spatial pair generation [#spatial-pair-generation]

Naively pairing every vessel with every other vessel is `O(n²)` in the active fleet, which is intractable at production fleet size. Instead, each AIS position is bucketed into its H3 resolution-6 parent cell (\~12 km edge, comparable to the 6 NM range gate). Within each cell, candidate pairs are generated as `{IMOs in cell} × {IMOs in cell ∪ 1-ring neighbour cells}`. The 1-ring expansion catches pairs that straddle a cell boundary; a canonical pair-key dedupe stops the same pair from being scored twice when both vessels are in the same cell.

Each run is bounded by a hard cap of 50,000 candidate pairs. If a window exceeds this, the function aborts with a `pair_explosion` error rather than running away — a guard against bad input data or pathological clustering.

### Direct invocation [#direct-invocation]

You can call the Edge Function directly to re-process a specific window — for example, after correcting upstream AIS data or for a forensic re-pull. Pass `since` and `until` as ISO 8601 timestamps; both are required when overriding the default 90-minute trailing window.

```bash
curl -X POST "$SUPABASE_URL/functions/v1/extract-encounters" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2026-04-15T00:00:00Z",
    "until": "2026-04-15T01:00:00Z"
  }'
```

The response includes counts for the run:

```json
{
  "ok": true,
  "positions": 18234,
  "pairs_evaluated": 1842,
  "encounters": 17,
  "epochs": 412,
  "since": "2026-04-15T00:00:00Z",
  "until": "2026-04-15T01:00:00Z"
}
```

Each run also writes a row to `ingestion_logs` with these counts and the window, so production runs are traceable from observability tooling.

### Backfilling history [#backfilling-history]

For multi-day re-processing — onboarding a new region, replaying after an algorithm change, or filling a gap — use the `backfill-encounters.mjs` driver. It chunks a `since → until` range into fixed-length windows and POSTs each one to the Edge Function in sequence:

```bash
# Last 7 days, 60-minute windows (default)
node scripts/backfill-encounters.mjs --days 7

# Explicit window
node scripts/backfill-encounters.mjs \
  --since 2026-04-01T00:00Z \
  --until 2026-04-08T00:00Z \
  --window-minutes 60

# Plan-only — print chunk count and exit without calling
node scripts/backfill-encounters.mjs --days 1 --dry-run
```

The driver requires `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` in the environment (or `--supabase-url` / `--service-key` flags). Because the Edge Function upserts on stable keys, re-running a botched chunk in place is safe — there is no need to drop rows before retrying.

As a runtime estimate: a 7-day backfill at 60-minute windows is 168 chunks; with the default 2-second sleep between chunks plus per-chunk Edge Function elapsed time, the full run takes roughly 10–20 minutes depending on position density.

## Rule and role posterior inference [#rule-and-role-posterior-inference]

Every encounter epoch is annotated with COLREGS-aligned rule posteriors (`p_head_on`, `p_overtaking`, `p_crossing`) and per-vessel role posteriors (`give_way_prob_a`, `stand_on_prob_a`, `give_way_prob_b`, `stand_on_prob_b`). The rule posteriors are normalized to sum to `1` and are derived from epoch geometry alone — no calibrated model, no priors from prior epochs, and no environmental context. This is enough to surface meaningful rule and role probabilities for screening, timeline reconstruction, and downstream COLREGS adjudication, and it lets consumers stop carrying `NULL`-handling branches on these columns.

### Rule posteriors [#rule-posteriors]

The three rule posteriors are produced by a smooth-step decision rule over course difference and the relative bearing each vessel sees of the other:

| Rule                 | Geometric gate                                                                                                                                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Head-on (Rule 14)    | Reciprocal courses (`course_diff_deg ≥ 175°`) **and** both vessels see the other near dead ahead (`\|rel_bearing_*_deg\| ≤ 7°`)                                                                                |
| Overtaking (Rule 13) | Near-parallel courses (`course_diff_deg ≤ 67.5°`) **and** one vessel sees the other forward of the beam while the other sees its counterpart more than 22.5° abaft the beam (`\|rel_bearing_*_deg\| > 112.5°`) |
| Crossing (Rule 15)   | Residual: `1 − p_head_on − p_overtaking`                                                                                                                                                                       |

Smooth thresholds rather than hard cutoffs mean a clean head-on (`Δc ≥ 178°`, `|θ| ≤ 2°`) drives `p_head_on ≥ 0.9`, a clean overtaking and a clean crossing each cross `0.85`, and ambiguous geometry produces a soft mixture instead of a brittle vote.

### Role posteriors [#role-posteriors]

Role posteriors are conditioned on the rule posteriors:

* **Head-on (Rule 14):** both vessels are required to alter course to starboard — neither has stand-on priority. `give_way_prob_*` and `stand_on_prob_*` each contribute `0.5` of the head-on mass to both vessels.
* **Overtaking (Rule 13):** the vessel that sees the other more forward (smaller `|rel_bearing|`) is the overtaker and is assigned the give-way mass; the overtaken vessel takes the stand-on mass.
* **Crossing (Rule 15):** the vessel with the other on its starboard side is give-way. Concretely, `pass_side_a = +1` means B is on A's starboard, so A is give-way; `−1` is the mirror; `0` (other vessel dead ahead/astern) splits the crossing mass 50/50.

### What the posteriors do not capture [#what-the-posteriors-do-not-capture]

* **No special-context axis yet.** `p_special_context` (TSS, narrow channel, RAM, tug-tow) requires TSS polygon ingestion and a `vessels.nav_status` join that are not yet wired in. The column ships `NULL` and will populate without a schema change when that lands.
* **No prior smoothing.** Each epoch is scored independently. A pair that flips between crossing and overtaking geometry near the threshold will see the posteriors flip with it; downstream consumers that need a single rule label per encounter should aggregate across the encounter window (e.g., the rule with the highest mean posterior over the risk window).
* **No nav-status priors.** A vessel `not_under_command` or `restricted_in_ability_to_manoeuvre` is treated identically to one underway and free to manoeuvre.

The numeric columns above are sufficient for current consumers — the [Risk API](/overwatch/api/risk) and [Investigations API](/overwatch/api/investigations) read them directly, and any downstream COLREGS adjudication can layer a calibrated model on top without touching the schema.

## Rule 17 deviation detection [#rule-17-deviation-detection]

Per COLREGS Rule 17(a)(i), the stand-on vessel **shall keep her course and speed**. Rule 17(a)(ii) and Rule 17(b) only authorise — and ultimately require — the stand-on vessel to manoeuvre when the give-way vessel is clearly failing to keep clear. A meaningful course alteration by a vessel with high stand-on probability is therefore unusual on its face: it typically indicates that the give-way side did not act in time and the stand-on side was forced to break stand-on to avert collision. The deviation itself is an evidence signal worth surfacing.

### When to use it [#when-to-use-it-1]

Reach for the Rule 17 deviation flags when you need to triage which encounters to read in detail rather than scan all of them. Typical use cases:

* Filtering for encounters where stand-on action was forced — i.e. likely give-way non-compliance
* Producing analyst worklists that lead with the encounters most likely to warrant manual COLREGS adjudication
* Annotating forensic timelines so investigators see the stand-on side's late maneuver as a first-class event, not a buried column on the epoch table

The flags are deterministic and geometry-only — they don't replace COLREGS adjudication, they prioritise which encounters to send to it.

### How the flags are computed [#how-the-flags-are-computed]

Each `pairwise_encounter` row carries two new pairs of columns: `max_course_change_{a,b}_deg` and `rule17_deviation_{a,b}`.

* **`max_course_change_*_deg`** — largest single-step course-over-ground delta observed for that vessel across the encounter epochs. Computed by walking the per-tick AIS COG snapshots stored on each epoch and taking the maximum wrapped delta between adjacent ticks.
* **`rule17_deviation_*`** — `TRUE` when **both** gates hold for that vessel, `FALSE` otherwise:
  * `max_course_change_*_deg ≥ 10°` — the maneuver was meaningful (small AIS-jitter wobble doesn't fire)
  * `mean(stand_on_prob_*)` across the encounter epochs `≥ 0.6` — the vessel was the stand-on side often enough that staying on course was the legal expectation

Both gates are required: a 30° turn from a give-way vessel is what Rule 17 expects (give-way is *supposed* to maneuver), so the flag stays `FALSE` there. A drifting stand-on vessel that wobbles 5° fires neither gate. The combination of "high mean stand-on probability AND a real course change" is what makes the boolean specifically a Rule 17 signal rather than a generic "vessel turned" indicator.

The thresholds are deliberately tuned conservatively for Phase 1 — false positives in either direction here propagate to analyst worklists, so the defaults err on the side of only firing when both conditions are clearly met. They're exported from `@axiom/core/processing/encounter-extraction` as `RULE17_MIN_COURSE_CHANGE_DEG` and `RULE17_MIN_MEAN_STAND_ON_PROB` so analyst tooling can probe with non-defaults without forking the algorithm.

### Querying for fired deviations [#querying-for-fired-deviations]

The columns are indexed for the common analyst query "show me encounters where a stand-on vessel was forced into action recently":

```sql
SELECT
  vessel_a_id, vessel_b_id, start_ts, cpa_ts,
  min_dcpa_nm,
  max_course_change_a_deg, rule17_deviation_a,
  max_course_change_b_deg, rule17_deviation_b
FROM pairwise_encounter
WHERE rule17_deviation_a OR rule17_deviation_b
ORDER BY start_ts DESC
LIMIT 100;
```

A partial index over `start_ts DESC` with the `rule17_deviation_a OR rule17_deviation_b` predicate keeps the worklist query cheap even at production fleet size.

### What the flags do not capture [#what-the-flags-do-not-capture]

Rule 17 deviation detection is the first phase of a broader compliance-evidence pipeline. The Phase 1 flags ship from pure geometry and AIS COG; richer signals are deliberately deferred to follow-up phases:

* **No counterfactual compliance distance.** The flag answers "did the stand-on vessel maneuver?" not "how much did the give-way vessel's path differ from a compliant one?". Counterfactual compliance distance requires a maneuver-prediction model and is a separate ticket.
* **No ghost-encounter inference.** Encounters that *would* have happened if the stand-on vessel had not maneuvered (i.e. the near-miss the deviation prevented) are not back-projected onto the encounter table. That requires the same prediction model as the counterfactual distance and lands in the same follow-up.
* **No nav-status priors.** A vessel `not_under_command` or `restricted_in_ability_to_manoeuvre` is treated identically to one underway and free to manoeuvre — the same caveat that applies to the rule and role posteriors above.
* **No special-context awareness.** Encounters inside a TSS or narrow channel can carry rule-specific overrides that change what "stand-on" means; that requires the same TSS polygon ingestion that gates `p_special_context` and is not yet wired in.

## Rule 17 handoff timestamp [#rule-17-handoff-timestamp]

Rule 17 deviation detection answers *whether* a stand-on vessel was forced into a meaningful maneuver across an encounter. The handoff timestamp answers *when* the legal authority for that maneuver activated — the moment Rule 17(a)'s "keep course and speed" obligation transitioned into Rule 17(b)/(c)'s "may / must take avoiding action." Surfacing T\* separately from the deviation flag is the operational disambiguation between **premature, unnecessary deviation** (the stand-on vessel broke course before authority transferred) and **required avoidance** (the stand-on vessel was already authorised, or compelled, to act).

### When to use it [#when-to-use-it-2]

Reach for the handoff timestamp when the deviation flag alone is too coarse — for example, when you need to:

* Distinguish a stand-on vessel that maneuvered *before* T\* (premature deviation, potentially itself a Rule 17 violation) from one that maneuvered *after* (required avoidance under Rule 17(b)/(c))
* Anchor a forensic timeline on the legal authority transition rather than on the geometric CPA, which usually lags T\* by several minutes
* Compare give-way inaction encounters against extremis encounters when prioritising analyst review — extremis means the geometry collapsed regardless of give-way behaviour and typically warrants the most urgent attention

If you only need a yes/no signal that the stand-on side acted, the [Rule 17 deviation flags](#rule-17-deviation-detection) are sufficient.

### How T\* is computed [#how-t-is-computed]

For each encounter, Overwatch first picks the canonical give-way side — whichever vessel has the higher mean `give_way_prob` across the encounter epochs — and then walks the epochs in chronological order. The first epoch that meets either trigger fires T\*; the earliest match wins.

| Trigger            | Gates                                                                                                                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extremis`         | `dcpa_nm < 0.1` (≈200 m). Geometry has already collapsed; Rule 17(c) compels stand-on action regardless of give-way behaviour. Short-circuits even if the give-way vessel is currently maneuvering.                                                                                 |
| `giveway_inaction` | `risk_prob > 0.70` **and** `dcpa_nm < 0.5` **and** the give-way vessel's max single-step COG change over the trailing 120-second action window is below 5°. Rule 17(b) authority for the stand-on vessel activates because the give-way vessel is observably failing to keep clear. |

Both triggers are deterministic and geometry-only. The thresholds are exported from `@axiom/core/processing/encounter-extraction` as `RULE17B_RISK_PROB_THRESHOLD`, `RULE17B_DCPA_THRESHOLD_NM`, `RULE17B_ACTION_WINDOW_S`, `RULE17B_GIVEWAY_ACTION_TOL_DEG`, and `RULE17B_EXTREMIS_DCPA_NM` so analyst tooling can probe with non-default values without forking the algorithm.

When neither trigger fires across the encounter, both `rule17_handoff_ts` and `rule17_handoff_trigger` ship `NULL`.

### Querying for fired handoffs [#querying-for-fired-handoffs]

A partial index on `rule17_handoff_ts DESC` keeps the common analyst worklist query — "show me encounters where Rule 17(b)/(c) authority transferred recently" — cheap at production fleet size:

```sql
SELECT
  vessel_a_id, vessel_b_id, start_ts, cpa_ts,
  rule17_handoff_ts, rule17_handoff_trigger,
  min_dcpa_nm,
  rule17_deviation_a, rule17_deviation_b
FROM pairwise_encounter
WHERE rule17_handoff_ts IS NOT NULL
ORDER BY rule17_handoff_ts DESC
LIMIT 100;
```

Combining the handoff timestamp with the deviation flags isolates the most analytically interesting cells:

* `rule17_handoff_ts IS NOT NULL` AND `rule17_deviation_*` true — the stand-on vessel maneuvered after authority transferred (required avoidance).
* `rule17_handoff_ts IS NOT NULL` AND both deviation flags false — authority transferred but neither vessel acted; the encounter likely closed on its own kinematics, or both vessels were dangerously passive.
* `rule17_handoff_ts IS NULL` AND `rule17_deviation_*` true — the stand-on vessel maneuvered before any handoff trigger fired (potential premature deviation).

### What the timestamp does not capture [#what-the-timestamp-does-not-capture]

The Phase 1 implementation emits T\* and the trigger only. Several richer signals are deliberately deferred:

* **No pre/post-handoff deviation magnitudes.** Phase 1 doesn't report how much each side maneuvered before vs. after T\*; that requires a maneuver-evidence accumulator the current emit-once pipeline doesn't carry, and lands in Phase 2.
* **No handoff confidence score.** The trigger is a hard boolean per epoch; there is no continuous score capturing how decisively each gate cleared. Also Phase 2.
* **No VTS or chokepoint hotspot aggregation.** Per-port and per-corridor handoff-rate rollups are a Phase 2 deliverable and are not yet exposed via the API.
* **No nav-status priors.** A give-way vessel `not_under_command` or `restricted_in_ability_to_manoeuvre` is treated identically to one underway and free to manoeuvre — the same caveat that applies to the rule and role posteriors.
* **No special-context awareness.** TSS and narrow-channel rule overrides aren't yet wired in; the handoff detector uses the same geometry-only inputs as the rest of the pipeline.

## COLREGS compliance scoring [#colregs-compliance-scoring]

Rule 17 deviation flags and the handoff timestamp answer *whether* and *when* a stand-on vessel was forced into action. Compliance scoring answers *how badly* the give-way vessel failed to keep clear — quantified as a counterfactual lateral distance between the give-way vessel's actual position at CPA and where it should have been under the minimum-effort compliant maneuver. A vessel that altered some-but-not-enough has a smaller deficit than one that didn't alter at all; the score explicitly rewards attempted compliance, not just successful outcomes.

Compliance scores live on a sibling table, `colregs_encounters`, keyed on `encounter_id`. One row exists per non-compliant encounter — encounters whose compliance deficit is zero or below the 0.05 NM write gate are silently dropped so the table doesn't fill up with clean passes.

### When to use it [#when-to-use-it-3]

Reach for compliance scoring when you need to rank or quantify non-compliance, not just flag it. Typical use cases:

* Triaging analyst worklists by deficit magnitude — encounters with the largest counterfactual deficit lead the queue
* Attributing partial credit when a give-way vessel began a maneuver but didn't alter enough — Rule 17 deviation flags treat that the same as inaction; deficit does not
* Producing per-vessel or per-fleet compliance distributions for forensic reporting and insurance underwriting
* Filtering encounters by encounter type (`head_on`, `overtaking`, `crossing`, `mixed`) when a downstream review is rule-specific

For a yes/no signal, the [Rule 17 deviation flags](#rule-17-deviation-detection) on `pairwise_encounter` are sufficient and don't require joining to `colregs_encounters`.

### How the score is computed [#how-the-score-is-computed]

For each encounter, the scorer first picks the canonical encounter type and give-way side, then computes the minimum starboard alteration that would have produced a safe DCPA, then measures how far the actual track was from that compliant alternative.


  
    ### Pick encounter type [#pick-encounter-type]

    `pickEncounterType` takes the argmax of `{p_head_on, p_overtaking, p_crossing}` at the epoch nearest `risk_window_start_ts`. When the maximum is below `0.55` the type collapses to `mixed` and the encounter is still scored, but consumers can filter on `encounter_type = 'mixed'` to exclude ambiguous geometry from rule-specific aggregations.
  

  
    ### Pick give-way side [#pick-give-way-side]

    `pickGiveWaySide` takes the argmax of `give_way_prob_a` and `give_way_prob_b` with a `0.10` ambiguity band. When the two probabilities are within the band, `give_way_imo` and `stand_on_imo` ship `NULL` and `role_certainty` reports the lower confidence — charitable to both vessels when the geometry doesn't clearly assign roles.
  

  
    ### Compute the required alteration [#compute-the-required-alteration]

    `computeRequiredStarboardDeg` runs a 1° linear search over `[0°, 90°]` for the minimum starboard course alteration on the give-way vessel that would have produced a DCPA at or above the safe threshold. The threshold is contextual: `0.5 NM` in `open_sea`, `0.2 NM` in `channel` / `tss` / `approach`, and `0.1 NM` in `anchorage`. When the actual `min_dcpa_nm` is already at or above the safe threshold, the encounter short-circuits as compliant: `compliance_deficit_nm = 0` and the row is dropped by the write gate.
  

  
    ### Measure the counterfactual deficit [#measure-the-counterfactual-deficit]

    The scorer then projects where the give-way vessel *would* have been at CPA had it held the required alteration from `risk_window_start_ts`, and returns the haversine distance between that counterfactual position and the actual position at CPA. That distance — in nautical miles — is `compliance_deficit_nm`.
  

  
    ### Capture both vessels' actual maneuver [#capture-both-vessels-actual-maneuver]

    `actual_starboard_deg_a` and `actual_starboard_deg_b` record each vessel's signed course delta from `risk_window_start_ts` to `cpa_ts` (positive = starboard). Both are stored because Rule 14 head-on requires *both* vessels to alter starboard; the per-vessel columns let downstream queries attribute non-compliance asymmetrically without re-deriving from epochs.
  


The scorer returns `NULL` (and the encounter is skipped) when `observed_fraction < 0.5`, fewer than 3 epochs cover the encounter, or the AIS straddle around `risk_window_start_ts` and `cpa_ts` is missing position data on either vessel. Skipped encounters land in the `skipped_low_conf` counter on each Edge Function run rather than producing a row.

### Output shape [#output-shape-1]

| Column                                               | Meaning                                                                                                  |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `encounter_id`                                       | Foreign key to `pairwise_encounter`; one-to-one                                                          |
| `encounter_type`                                     | `head_on` / `overtaking` / `crossing` / `mixed`                                                          |
| `rule_certainty`                                     | Maximum rule posterior at the risk-start epoch, in `[0, 1]`                                              |
| `give_way_imo`, `stand_on_imo`                       | IMO of the resolved roles; `NULL` when within the `0.10` ambiguity band                                  |
| `role_certainty`                                     | Confidence on the role assignment, in `[0, 1]`                                                           |
| `required_maneuver_type`                             | `starboard_alter` / `pass_clear` / `no_action`                                                           |
| `required_starboard_deg`                             | Minimum starboard alteration that would have cleared the safe DCPA threshold; `NULL` when not applicable |
| `actual_starboard_deg_a`, `actual_starboard_deg_b`   | Each vessel's actual signed Δcourse from risk-start to CPA, in degrees                                   |
| `compliance_deficit_nm`                              | Counterfactual lateral distance — the principal score                                                    |
| `safe_dcpa_threshold_nm`                             | Context-tag-driven DCPA target used in the solver                                                        |
| `min_dcpa_nm`, `observed_fraction`, `encounter_conf` | Mirrored from `pairwise_encounter` for query convenience                                                 |
| `analyst_state`                                      | `auto` / `reviewed` / `cleared` / `escalated` — operator workflow                                        |
| `notes`                                              | Free-text annotation from analyst review                                                                 |
| `created_at`, `updated_at`                           | Audit timestamps                                                                                         |

Three indexes back the common analyst queries: `compliance_deficit_nm DESC` (filtered to deficits above the write gate), `(encounter_type, created_at DESC)`, and `give_way_imo` (filtered to non-null). RLS allows read-all; writes are service-role only.

### Production pipeline [#production-pipeline-1]

The `score-colregs-compliance` Edge Function runs hourly at minute `:17` — ten minutes after `extract-encounters` lands at `:07`, so each run scores the encounters extracted in the previous hour. The function fetches unscored `pairwise_encounter` rows in the trailing 24-hour window, pulls each encounter's `encounter_epoch` rows and the bracketing `ais_positions` for both vessels in parallel, scores in memory via `@axiom/core/processing/colregs-compliance`, and bulk-upserts in 200-row chunks (PostgREST authenticator timeout safety). Re-runs are idempotent — `encounter_id` is the primary key, so re-scoring an already-scored encounter updates the existing row rather than inserting a duplicate.

The write gate is a deliberate filter, not a confidence floor: encounters whose `compliance_deficit_nm <= 0.05 NM` are dropped because the table is meant to be a worklist of *failures*, not a comprehensive scoreboard of every encounter. Already-compliant traffic is recoverable from `pairwise_encounter` directly.

### Direct invocation [#direct-invocation-1]

You can re-process a specific window — for forensic re-pulls, or after correcting upstream encounter data — by POSTing `since` and `until` overrides:

```bash
curl -X POST "$SUPABASE_URL/functions/v1/score-colregs-compliance" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2026-04-15T00:00:00Z",
    "until": "2026-04-15T01:00:00Z"
  }'
```

The response includes counts for the run:

```json
{
  "ok": true,
  "evaluated": 42,
  "scored": 11,
  "skipped_low_conf": 6,
  "skipped_compliant": 25,
  "elapsed_ms": 1843
}
```

`evaluated` is the number of unscored encounters in the window, `scored` is rows actually written (deficit above the gate), `skipped_low_conf` is encounters with insufficient AIS coverage or low observed fraction, and `skipped_compliant` is encounters whose deficit was at or below `0.05 NM`. Each run also writes an `ingestion_logs` row with these counts under `source = 'score_colregs_compliance'`, so production runs are traceable from the [status page](/overwatch/status-page).

### Backfilling history [#backfilling-history-1]

For multi-day backfills — onboarding a new region, replaying after an algorithm change, or filling in scoring gaps — use the `backfill-colregs.mjs` driver. It chunks a `since → until` range into fixed-length windows (default 6 hours; encounter density is modest and scoring is light, so chunks are larger than for extraction) and POSTs each chunk to the Edge Function in sequence:

```bash
# Last 7 days, 6-hour windows (default)
node scripts/backfill-colregs.mjs --days 7

# Explicit window with custom chunk size
node scripts/backfill-colregs.mjs \
  --since 2026-04-01T00:00Z \
  --until 2026-04-08T00:00Z \
  --window-minutes 360

# Plan-only — print chunk count and exit without calling
node scripts/backfill-colregs.mjs --days 1 --dry-run
```

The driver reads `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` from the environment (or accepts `--supabase-url` / `--service-key` flags). Because the Edge Function upserts on `encounter_id`, re-running a botched chunk in place is safe — there is no need to drop rows before retrying.

### Querying for non-compliant encounters [#querying-for-non-compliant-encounters]

The most common analyst query — "show me the worst recent non-compliance, ranked by deficit" — is backed by the descending `compliance_deficit_nm` partial index:

```sql
SELECT
  c.encounter_id,
  c.encounter_type,
  c.give_way_imo,
  c.stand_on_imo,
  c.required_starboard_deg,
  c.actual_starboard_deg_a,
  c.actual_starboard_deg_b,
  c.compliance_deficit_nm,
  c.safe_dcpa_threshold_nm,
  p.cpa_ts,
  p.context_tag
FROM colregs_encounters c
JOIN pairwise_encounter p USING (encounter_id)
WHERE c.compliance_deficit_nm > 0.05
  AND p.cpa_ts >= NOW() - INTERVAL '7 days'
ORDER BY c.compliance_deficit_nm DESC
LIMIT 100;
```

Combining the deficit with the [Rule 17 deviation flags](#rule-17-deviation-detection) on `pairwise_encounter` separates the most analytically interesting cells: a large deficit *and* `rule17_deviation_*` true on the stand-on side is the classic "give-way did nothing, stand-on was forced to break stand-on" pattern.

### What the score does not capture [#what-the-score-does-not-capture]

* **No ghost-vessel inference.** `ghost_inference_vector` ships `NULL` for every row. The column is reserved for back-projecting the near-miss the stand-on side's deviation prevented, and lands in a follow-up that needs a maneuver-prediction model.
* **`pairwise_encounter.context_tag` is not yet populated.** Until the spatial-context classifier lands, every encounter falls back to the `open_sea` `0.5 NM` safe-DCPA threshold. Channel, TSS, approach, and anchorage encounters are scored against a more permissive threshold than they should be — the deficit is a lower bound until context tagging ships.
* **No nav-status priors.** A give-way vessel `not_under_command` or `restricted_in_ability_to_manoeuvre` is treated identically to one underway and free to manoeuvre — the same caveat that applies to the rule and role posteriors and the Rule 17 detectors above.
* **No special-context awareness.** TSS and narrow-channel rule overrides aren't yet wired in; the solver uses geometry-only inputs.
* **No multi-encounter aggregation.** Each encounter is scored independently. Per-vessel non-compliance rates and per-corridor hotspot rollups are not yet exposed via the API and require ad-hoc aggregation against `colregs_encounters`.

The deficit is intended for analyst triage and forensic review — it is not a calibrated COLREGS adjudication, and a non-zero deficit is not a finding of fault.

## What the extractor doesn't do [#what-the-extractor-doesnt-do]

* **No interpolation** — every epoch is grounded in a real AIS report. Long gaps between fixes show up as long inter-epoch intervals, not synthetic samples.
* **No heading-only inference** — vessels missing speed or course are skipped for that epoch.
* **No environmental context** — currents, traffic separation rules, and depth restrictions are not modeled in the geometry-only `risk_prob`.
* **No collision adjudication** — `risk_prob` is a screening signal for downstream review, not an authoritative collision-risk verdict.

## Related references [#related-references]

* [Vessels API](/overwatch/api/vessels) — single-vessel position and identity data feeding the extractor
* [Risk API](/overwatch/api/risk) — surfaces encounter-derived risk indicators
* [Investigations API](/overwatch/api/investigations) — case files that pull encounter timelines into a forensics view


# Entity resolution (/overwatch/methodology/entity-resolution)



Axiom Overwatch resolves real-world entities — companies, vessel owners, sanctioned parties, permit applicants — across noisy data sources by running probabilistic record-linkage with [Splink](https://moj-analytical-services.github.io/splink/). High-probability candidate pairs are persisted to `entity_resolution_pairs` and an analyst either confirms, rejects, or marks them as unsure through the adjudication API before any downstream consumer treats them as the same entity.

This is the foundation for investigation case-file consolidation, sanctions screening across naming variants, and UBO chain stitching where a single owner appears under spelling, jurisdiction, or registration-number differences in upstream feeds.

## When to use it [#when-to-use-it]

Reach for entity resolution when you need to answer "is this the same company / owner / party as that one?" across heterogeneous records — not "does this string match that string." Typical use cases:

* Collapsing duplicate companies across LEI, OpenSanctions, Equasis, and registry feeds before an [investigation case file](/overwatch/api/investigations) is built
* Stitching ownership chains where one party appears under multiple names, transliterations, or registration numbers
* De-duplicating permit applicants before [sanctions](/overwatch/api/sanctions) or [UBO](/overwatch/api/ubo) screening
* Producing an adjudication worklist for analyst review when automated matching is not safe to act on alone

If you only need a deterministic join on a known key — IMO, MMSI, LEI, `record_id` — use the standard [Codex join keys](/codex/join-keys) instead. Probabilistic resolution is for the cases where deterministic keys are missing, inconsistent, or contested.

## How resolution works [#how-resolution-works]

For each input table, Splink streams every candidate pair through a settings-driven scorer: blocking rules narrow the candidate space, comparison vectors score the surviving pairs, and an unsupervised expectation-maximisation training step learns the per-field match weights without labelled examples.




  
    ### Snapshot input [#snapshot-input]

    The linker reads from a Parquet snapshot of the source table, never from live Supabase. This keeps training reproducible, lets a model version be re-trained against a fixed input, and prevents long-running linkage jobs from contending with operational reads.
  

  
    ### Block candidate pairs [#block-candidate-pairs]

    Blocking rules narrow the `O(n²)` pair space to a tractable candidate set. The companies linker blocks on a 4-character name prefix, jurisdiction plus first letter of the name, and shared non-null LEI code.
  

  
    ### Score with comparison vectors [#score-with-comparison-vectors]

    Each surviving pair is scored across the comparison vector — name (Jaro–Winkler at 0.9 and 0.7), jurisdiction (exact match with term-frequency adjustment), registration number (exact match), and legal-form code (Levenshtein at distance 1 and 3 for companies).
  

  
    ### Estimate parameters [#estimate-parameters]

    Unsupervised EM training estimates `m` and `u` probabilities per comparison level from the data itself. The two-random-records baseline is anchored on deterministic rules (LEI match, registration-number match, jurisdiction-plus-uppercase-name match) at `recall = 0.8`, and `u` is estimated from one million random pair samples.
  

  
    ### Persist candidate pairs [#persist-candidate-pairs]

    Predictions with `match_probability >= 0.95` are upserted to `entity_resolution_pairs` in batches of 500, keyed on `(model_version, id_l, id_r)`. Below `0.95` is discarded — the table is a high-confidence worklist, not a comprehensive scoreboard.
  

  
    ### Adjudicate [#adjudicate]

    Each persisted pair starts at `adjudication_status = 'pending'`. An analyst confirms (`match`), rejects (`not_match`), or defers (`unsure`) through the adjudication API. Only pairs marked `match` are safe for downstream consumers — investigation case-file merge, dedup on Aleph ingest, UBO chain stitching — to treat as the same entity.
  


## The companies linker [#the-companies-linker]

The first linker covers the `companies` table and runs in Splink's `dedupe_only` mode — same source on both sides of the pair. Address deduplication is intentionally out of scope; address normalization is handled separately by libpostal upstream.

| Setting               | Value                       |
| --------------------- | --------------------------- |
| Link type             | `dedupe_only`               |
| Unique ID column      | `id`                        |
| Persistence threshold | `match_probability >= 0.95` |
| Batch size            | 500 rows per upsert         |
| Default model version | `splink_companies_v0.1`     |

Cross-table `link_only` jobs (`gleif` × `opensanctions` × `equasis`) are a follow-up — the scaffolding supports them, but no production linker for those targets has shipped yet.

### Configuring a run [#configuring-a-run]

The linker is exposed from `packages/python-services/splink` and is invoked from a Python worker, not an Edge Function. Pass the path to a Parquet snapshot of the input table:

```python
from supabase import create_client
from companies_linker import (
    train_companies_linker,
    predict_and_persist_companies,
)

linker = train_companies_linker("/path/to/companies.parquet")

supabase = create_client(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)
count = predict_and_persist_companies(linker, supabase)
print(f"persisted {count} candidate pairs")
```

To override the model version or threshold for an experiment, pass them through:

```python
count = predict_and_persist_companies(
    linker,
    supabase,
    model_version="splink_companies_v0.2",
    threshold=0.97,
)
```

The default `splink_

_v.` versioning convention is enforced by the upsert key `(model_version, id_l, id_r)` — a new version produces a fresh set of candidate pairs alongside the old ones rather than overwriting them, so analysts can compare two versions against the same input.

When to bump versions:

* **Minor** — thresholds, blocking rules, or comparison settings change but the entity target is the same.
* **Major** — the input table contract, link type, or downstream semantics change.

## The `entity_resolution_pairs` table [#the-entity_resolution_pairs-table]

Every persisted candidate pair lands in `public.entity_resolution_pairs` with the standard APRS envelope (`record_id`, `schema_version`, `normalization_version`, `acl_tier`, `source_system`, `ingested_at`, `modified_at`, `chunk_id`) plus resolution-specific columns:

| Column                             | Meaning                                                                                                                               |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `model_version`                    | `splink_

_v.` — identifies which trained model produced the pair                                                  |
| `source_table_l`, `source_table_r` | Source tables for the left and right side of the pair. Same value for `dedupe_only` runs; different for cross-table `link_only` runs. |
| `id_l`, `id_r`                     | Local IDs from each source table                                                                                                      |
| `match_probability`                | Splink-derived probability in `[0, 1]`; only pairs at or above the persistence threshold are stored                                   |
| `match_weight`                     | Log-odds match weight from Splink                                                                                                     |
| `blocking_rule`                    | The blocking rule that surfaced the pair                                                                                              |
| `adjudication_status`              | `pending` / `match` / `not_match` / `unsure`                                                                                          |
| `adjudicated_by`                   | UUID of the analyst who decided; `NULL` until decided                                                                                 |
| `adjudicated_at`                   | Timestamp of the decision; `NULL` until decided                                                                                       |

The table enforces a unique constraint on `(model_version, id_l, id_r)` so re-running the same model against the same input is idempotent — re-runs update existing rows in place rather than inserting duplicates. Indexes on `adjudication_status`, `match_probability DESC`, `(source_table_l, id_l)`, and `(source_table_r, id_r)` back the common worklist and reverse-lookup queries.

Row-level security is configured for service-role writes and authenticated reads — only the Splink workers (and other service-role callers) can persist or update candidate pairs, but any authenticated analyst can read them.

## Adjudication API [#adjudication-api]

The adjudication API exposes two endpoints under the `entity-resolution` tag for analyst tooling — an inbox endpoint and a decision endpoint.

### `GET` `/pending` [#get-pending]

Returns pending pairs ordered by descending match probability, so the strongest candidates are reviewed first.

**Parameters**

| Name    | Type   | Required | Description                                            |
| ------- | ------ | -------- | ------------------------------------------------------ |
| `limit` | number |          | Number of pairs to return. Default 50, min 1, max 500. |

**Response**

```json
{
  "pairs": [
    {
      "id": 1842,
      "model_version": "splink_companies_v0.1",
      "source_table_l": "companies",
      "source_table_r": "companies",
      "id_l": "co_018af1c2",
      "id_r": "co_0aa39e44",
      "match_probability": 0.987,
      "match_weight": 6.12,
      "blocking_rule": "l.lei_code = r.lei_code and l.lei_code is not null",
      "adjudication_status": "pending",
      "ingested_at": "2026-05-19T09:00:00Z"
    }
  ]
}
```

### `POST` `/decide` [#post-decide]

Records an analyst's decision on a pair.

**Body**

| Field            | Type    | Required | Description                                            |
| ---------------- | ------- | -------- | ------------------------------------------------------ |
| `pair_id`        | integer | ✓        | Primary key of the `entity_resolution_pairs` row       |
| `decision`       | string  | ✓        | One of `match`, `not_match`, `unsure`                  |
| `adjudicated_by` | UUID    |          | Analyst identifier; optional but recommended for audit |

```bash
curl -X POST "$OVERWATCH_API_URL/entity-resolution/decide" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pair_id": 1842,
    "decision": "match",
    "adjudicated_by": "00000000-0000-0000-0000-000000000001"
  }'
```

The endpoint updates `adjudication_status`, stamps `adjudicated_at` and `modified_at` to the current UTC time, and optionally records `adjudicated_by`. A `404` is returned when no row matches `pair_id`.

## Gold-set evaluation [#gold-set-evaluation]

Before promoting a model version — that is, before any downstream consumer is allowed to treat its `match` decisions as authoritative — every model goes through a 200-row gold-set evaluation:

1. Sample 100 pairs from the high-confidence band (`match_probability >= 0.95`), 50 from the review band (`0.80 <= match_probability < 0.95`), and 50 hard negatives below `0.80`.
2. Have an analyst label each pair as `match`, `not_match`, or `unsure` through the adjudication API.
3. Compute precision, recall proxy, false-positive themes, and threshold sensitivity against the 200 labels.
4. Record the gold-set date, model version, input snapshot URI, and metrics before enabling downstream consumers.

A model that hasn't passed gold-set evaluation can still produce candidate pairs and feed the adjudication queue, but its decisions are not yet wired into investigation case-file merge or sanctions screening.

## What the linker doesn't do [#what-the-linker-doesnt-do]

* **No live-table linkage.** All inputs are read from Parquet snapshots. Training against operational Supabase tables is explicitly disallowed.
* **No address deduplication.** Addresses are normalized upstream by libpostal; the companies linker doesn't include any address comparison.
* **No automatic merge.** Persisted pairs are candidates, not decisions. Nothing downstream treats two records as the same entity until an analyst sets `adjudication_status = 'match'`.
* **No cross-table link jobs yet.** The scaffolding supports `link_only` mode, but no production cross-table linker (`gleif` × `opensanctions` × `equasis`) has shipped.
* **No supervised training.** The linker relies on unsupervised EM and deterministic anchor rules; no labelled training set is required to produce candidate pairs.

## Related references [#related-references]

* [Investigations API](/overwatch/api/investigations) — case-file consolidation that consumes confirmed matches
* [Sanctions API](/overwatch/api/sanctions) — sanctions screening across name and jurisdiction variants
* [UBO API](/overwatch/api/ubo) — beneficial-ownership chains that benefit from cross-source deduplication
* [Cross-dataset join keys](/codex/join-keys) — deterministic keys to prefer over probabilistic resolution when available


# FollowTheMoney projections (/overwatch/methodology/ftm-projections)



Axiom Overwatch stores a [FollowTheMoney](https://followthemoney.tech) (FTM) projection alongside the native row for every entity-producing table. The projection is a small, Aleph-compatible JSON document — schema name plus a property bag of string arrays — written to an `ftm JSONB` column. Downstream consumers (Aleph sync, entity resolution, the investigations graph, Cytoscape views) read the projection instead of joining across producer-specific shapes, so a vessel, a permit applicant, a sanctioned entity, and a council decision are all addressable through one wire format.



## When to use it [#when-to-use-it]

Reach for the `ftm` column when you need a cross-producer view of entities, not the producer-specific row. Typical use cases:

* Joining a sanctioned company to its LEI record and to any zoning permits it has filed
* Pushing a slice of the entity graph into [Aleph](https://docs.aleph.occrp.org/) for cross-jurisdiction search
* Running entity resolution (for example Splink) over a single canonical entity shape
* Driving a Cytoscape or visx investigation graph without writing per-table adapters

If you only need fields from one producer — vessel positions, a permit's filing date, the raw GLEIF response — keep reading the native columns. The projection is additive; it never replaces the source row.

## Wire format [#wire-format]

Every `ftm` value is a single object with three fields:

```json
{
  "id": "urn:axiom:Company:gleif:5493001KJTIIGC8Y1R12",
  "schema": "Company",
  "properties": {
    "name": ["ACME GRAIN EXPORTS LLC"],
    "leiCode": ["5493001KJTIIGC8Y1R12"],
    "jurisdiction": ["US-DE"],
    "registrationNumber": ["5493001KJTIIGC8Y1R12"]
  }
}
```

Three invariants hold across every projection:

* **All property values are arrays of strings**, even when a single value is set. Consumers can iterate without branching on type.
* **URNs follow `urn:axiom:::`**, where `` identifies the producer table (`gleif`, `zoning_permits`, `council_decisions`, `overwatch_vessels`, …) and `` is the producer's primary key. The schema segment in the URN must match the `schema` field.
* **Partial projections are stored as `NULL`.** If a producer cannot fill the minimum required properties for a schema, it writes `ftm = NULL` rather than a half-filled object. Consumers can therefore treat the presence of `ftm` as a signal the projection is complete.

## Schemas [#schemas]

The projection uses a fixed set of FTM-compatible schemas. Each producer commits to one or more of them:

| Producer table                      | Schemas emitted                                        | Key properties                                                                                                                |
| ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `gleif_lei_records`                 | `Company`                                              | `name`, `leiCode`, `legalForm`, `jurisdiction`, `registrationNumber`, `address`, `status`, `sourceUrl`                        |
| `zoning_permits`                    | `Company` or `Person` (applicant), `Event` (lifecycle) | applicant: `name`, `address`; event: `name`, `date`, `location`, `involved`, `summary`, `description`, `recordId`             |
| `council_decisions`                 | `Event` (decision), `PublicBody` (issuing body)        | event: `name`, `date`, `organizer`, `summary`, `location`, `sourceUrl`, `recordId`; body: `name`, `jurisdiction`, `sourceUrl` |
| Overwatch vessels                   | `Vessel`                                               | `imoNumber`, `name`, `flag`, `type`, `owner`, `operator`                                                                      |
| Ownership edges                     | `Ownership`                                            | `owner`, `asset`, `percentage`, `startDate`, `endDate`, `recordId`                                                            |
| `sanctions_hits`                    | `Sanction`                                             | `entity`, `authority`, `program`, `reason`, `startDate`, `endDate`, `sourceUrl`                                               |
| Document queues                     | `Document`                                             | `title`, `fileName`, `sourceUrl`, `date`, `author`, `publisher`                                                               |
| Source-specific assets and payments | `Asset`, `Payment`                                     | identity fields and payment counterparties / value                                                                            |

The `zoning_permits` applicant projection uses a `LLC|INC|CORP|LP|LTD|…` heuristic to split companies from natural persons. A name that matches is projected as a `Company`; everything else falls through to `Person` with a `firstName` / `lastName` split on whitespace.

## Storage [#storage]

The `ftm` column lives on the producer table itself — there is no separate projection table — and is indexed for the two query shapes consumers actually need:

* `((ftm->>'schema'))` — a btree expression index so `WHERE ftm->>'schema' = 'Company'` is cheap when fanning out by entity type.
* `(ftm jsonb_path_ops)` — a GIN index so containment queries (`ftm @> '{"properties":{"leiCode":["5493…"]}}'`) hit an index instead of scanning the producer table.

Both indexes are partial-friendly: rows where `ftm IS NULL` are skipped, so they cost nothing on producers that have not finished backfilling.

```sql
-- All companies with a given LEI, across every producer that emits Company.
SELECT id, ftm
FROM gleif_lei_records
WHERE ftm @> '{"properties": {"leiCode": ["5493001KJTIIGC8Y1R12"]}}';

-- All events tied to a metro, regardless of which producer wrote them.
SELECT id, ftm
FROM council_decisions
WHERE ftm->>'schema' = 'Event'
  AND ftm @> '{"properties": {"location": ["nyc"]}}';
```

## Querying across producers [#querying-across-producers]

Because every producer uses the same wire format, you can `UNION ALL` across tables to assemble a typed slice of the entity graph without per-producer adapters:

```sql
SELECT 'gleif' AS source, ftm
FROM gleif_lei_records
WHERE ftm->>'schema' = 'Company'

UNION ALL

SELECT 'zoning_permits' AS source, ftm
FROM zoning_permits
WHERE ftm->>'schema' = 'Company';
```

Use the `id` field (the canonical URN) as the join key when feeding entity resolution. Two producers that emit a `Company` for the same LEI will share `leiCode` in their property bag but will keep distinct `id` values — resolution happens in the consumer, not in the producer.

## Producing FTM entities [#producing-ftm-entities]

Server-side producers (Edge Functions, ingest scripts, the civic document pipeline) build projections through the `@axiom/ftm` package, which ships builders, adapters per producer table, and a zod validator. The validator runs before the row is upserted; producers either write a fully-formed entity or `NULL`.

```ts
import { companyFromGleif, validateFtmEntity } from '@axiom/ftm'

const entity = companyFromGleif({
  lei: row.lei,
  legal_name: row.legal_name,
  legal_form_code: row.legal_form_code,
  jurisdiction: row.jurisdiction,
  registered_address: row.registered_address,
  entity_status: row.entity_status,
  source_url: row.source_url,
})

if (entity) {
  await supabase
    .from('gleif_lei_records')
    .update({ ftm: validateFtmEntity(entity) })
    .eq('lei', row.lei)
}
```

The builder enforces minimum-property gates per schema — for example, a `Company` projection requires `name`, and a `Vessel` projection requires `imoNumber`. If the gate fails, the adapter returns `null` and the producer writes `ftm = NULL` rather than a partial object.

## Validation rules [#validation-rules]

`validateFtmEntity` rejects four classes of malformed input:

* A scalar (or non-array) property value — every property must be an array of strings.
* An empty property bag — projections with no properties are not addressable and would defeat the index.
* A URN that does not match the documented `urn:axiom:::` shape.
* A URN whose schema segment disagrees with the entity's `schema` field.

Acceptance for AXL-229 is a producer validation rate above 99% — the small remainder is rows where the source is missing the minimum required fields (no `legal_name` on a GLEIF row, no `applicant_name` on a permit) and the projection is correctly stored as `NULL`.

## Backfill and freshness [#backfill-and-freshness]

The `ftm` column is populated forward by producers as they ingest new rows. Existing rows are backfilled by the same adapter run against historical data; no row-level migration is required because the column is nullable and the indexes are GIN/expression-based.

Consumers that need a complete snapshot — for example, an Aleph sync — should filter on `ftm IS NOT NULL` and rely on the producer's own freshness signal in `ingestion_logs` to decide whether to wait for a backfill pass to complete.


# Route forecasts (/overwatch/methodology/route-forecasts)



For every vessel currently in transit, Axiom Overwatch projects a great-circle waypoint sequence to the vessel's declared destination port and an ETA distribution (p10 / p50 / p90) at each waypoint. This gives downstream consumers a forward-looking view of where every active vessel is going and when it is expected to arrive — at the ship level, not just at the port aggregate level.

## When to use this [#when-to-use-this]

* Power a vessel detail view that shows the projected path and arrival window
* Estimate inbound cargo arrivals by joining forecasts to draft-derived tonnage
* Monitor vessels that are running materially behind their declared ETA
* Pre-position alerts based on which vessels will reach a region in the next 24 / 48 / 72 hours

If you only need port-level cargo volume forecasts, use the [Forecasts API](/overwatch/api/forecasts). Use the route-forecast dataset when you need a per-vessel, per-waypoint breakdown.

## What gets forecast [#what-gets-forecast]

Route forecasts are produced for vessels that meet **all** of these conditions on the hourly run:

* Latest AIS position is less than 6 hours old
* Vessel is **outside** every defined `port_zone` (entering port-call mechanics is out of scope)
* Vessel has a non-null AIS-declared destination string
* Resolved destination is at least **30 nautical miles** away

Vessels that fail any of these checks are silently skipped on the run and re-evaluated the next hour.

## The dataset [#the-dataset]

Each qualifying vessel produces one **forecast row** per hourly run plus eight **waypoint rows** keyed by `forecast_id`. Old rows are retained so accuracy can be backtested later.

### `vessel_route_forecasts` [#vessel_route_forecasts]

| Field                                | Description                                                                             |
| ------------------------------------ | --------------------------------------------------------------------------------------- |
| `id`                                 | UUID, primary key.                                                                      |
| `imo_number`                         | Vessel IMO. References `vessels`.                                                       |
| `visit_id`                           | Linked `vessel_visits` row when the forecast can be tied to an open visit. May be null. |
| `origin_lat`, `origin_lng`           | Vessel position at forecast time.                                                       |
| `origin_timestamp`                   | AIS timestamp of the position the forecast was projected from.                          |
| `destination_port_id`                | Resolved port UUID. References `ports`.                                                 |
| `destination_raw`                    | Raw AIS destination string (preserved for audit).                                       |
| `destination_lat`, `destination_lng` | Centroid of the resolved destination port.                                              |
| `current_speed_knots`                | SOG at forecast time.                                                                   |
| `total_distance_nm`                  | Great-circle distance from origin to destination.                                       |
| `forecast_method`                    | Versioned method tag. Currently `great_circle_v1`.                                      |
| `computed_at`                        | Timestamp the forecast was written.                                                     |

### `vessel_route_forecast_waypoints` [#vessel_route_forecast_waypoints]

Eight rows per forecast (`waypoint_index` 0 through 7). Index 0 is the origin, index 7 is the destination, and the six intermediate points are spaced evenly along the great-circle arc.

| Field                    | Description                                                                |
| ------------------------ | -------------------------------------------------------------------------- |
| `forecast_id`            | FK to `vessel_route_forecasts` (cascade delete).                           |
| `waypoint_index`         | 0 to 7.                                                                    |
| `lat`, `lng`             | Waypoint coordinates on the great circle.                                  |
| `cumulative_distance_nm` | Distance from origin along the arc.                                        |
| `eta_p10`                | Optimistic arrival timestamp (vessel sustains 20% above projection speed). |
| `eta_p50`                | Median arrival timestamp at projection speed.                              |
| `eta_p90`                | Pessimistic arrival timestamp (vessel runs 30% below projection speed).    |

## How it's computed [#how-its-computed]

Each hour at minute :25 (offset from AIS polling at :15 and the latest-positions matview refresh) the `compute-route-forecasts` job runs:



1. **Pull active vessels.** Read `mv_latest_positions` filtered to non-null destinations within the last 6 hours, capped at 500 vessels per run.
2. **Resolve the destination.** Match the AIS destination string against the `ports_with_centroid` view via a four-step cascade — exact slug, exact name, last whitespace-separated tail token (handles strings like `NL RTM > BR SSZ`), then a final `ILIKE` fragment match. Skip the vessel if no port resolves.
3. **Filter port-call mechanics.** Skip vessels currently inside any `port_zone` (resolved via the `point_inside_any_port_zone` PostGIS RPC) and vessels within 30 NM of their destination.
4. **Build the great-circle arc.** Slerp eight waypoints between origin and destination centroid on a unit sphere.
5. **Compute the ETA distribution.** Project ETA at each waypoint using `cumulative_distance / projection_speed`. The p10 band is 20% faster than p50 and the p90 band is 30% slower (vessels lose more speed than they add).
6. **Persist** one forecast row plus eight waypoint rows.

### Projection speed [#projection-speed]

The projection speed is the vessel's current SOG when SOG is at least 5 knots. Below that threshold the SOG is considered too noisy or stationary to extrapolate (drifting, engine-down, or spoofed-stationary) and the run falls back to a class-typical cruise speed:

| Vessel class  | Fallback speed (knots) |
| ------------- | ---------------------- |
| Container     | 18                     |
| Ro-Ro         | 17                     |
| LNG           | 16                     |
| Reefer        | 14                     |
| Tanker        | 13                     |
| Bulker        | 12                     |
| General cargo | 11                     |
| Unknown       | 12                     |

The same projection speed is used for every waypoint in a single forecast. The next hourly run picks up any speed change.


  `great_circle_v1` does not account for weather routing, traffic separation schemes, or piracy avoidance corridors. The forecast is a clean great-circle projection. A future `weather_routed_v1` method will retain the same schema with a different `forecast_method` tag.


## Querying [#querying]

The dataset lives in `vessel_route_forecasts` and `vessel_route_forecast_waypoints`. Both tables are RLS-protected with read-all and service-role-write policies. Indexes on `(imo_number, computed_at DESC)` and `(destination_port_id, computed_at DESC)` cover the most common access patterns.

```sql
-- Latest forecast for one vessel, with its eight waypoints in order.
select
  f.imo_number,
  f.destination_port_id,
  f.total_distance_nm,
  f.current_speed_knots,
  w.waypoint_index,
  w.lat,
  w.lng,
  w.cumulative_distance_nm,
  w.eta_p10,
  w.eta_p50,
  w.eta_p90
from vessel_route_forecasts f
join vessel_route_forecast_waypoints w on w.forecast_id = f.id
where f.imo_number = $1
order by f.computed_at desc, w.waypoint_index asc
limit 8;
```

```sql
-- All vessels with a p50 ETA inside the next 48 hours at a destination port.
select distinct on (f.imo_number)
  f.imo_number,
  f.current_speed_knots,
  w.eta_p50 as expected_arrival,
  w.eta_p10 as earliest,
  w.eta_p90 as latest
from vessel_route_forecasts f
join vessel_route_forecast_waypoints w on w.forecast_id = f.id
where f.destination_port_id = $1
  and w.waypoint_index = 7
  and w.eta_p50 between now() and now() + interval '48 hours'
order by f.imo_number, f.computed_at desc;
```

```sql
-- Plot the projected great-circle path as a line for the latest forecast.
select array_agg(
  array[w.lng, w.lat] order by w.waypoint_index
) as line
from vessel_route_forecasts f
join vessel_route_forecast_waypoints w on w.forecast_id = f.id
where f.imo_number = $1
  and f.computed_at = (
    select max(computed_at) from vessel_route_forecasts where imo_number = $1
  );
```

## Helper view and RPC [#helper-view-and-rpc]

The migration ships two reusable helpers because `ports` itself has no lat/lng columns:

* `ports_with_centroid` — view exposing `(id, slug, name, country, lat, lng)` derived from each port's `port_zones` geometry. Prefers the `geofence` zone and falls back to any zone. `SECURITY INVOKER`, granted to `anon`, `authenticated`, and `service_role`.
* `point_inside_any_port_zone(p_lat numeric, p_lng numeric)` — `STABLE` PostGIS RPC returning `true` when the point sits inside any defined port zone.

Both are useful outside the forecaster. Use the view whenever you need a port centroid without joining `port_zones` manually.

```sql
-- Top 10 ports closest to a given lat/lng.
select id, slug, name,
  earth_distance(
    ll_to_earth($1, $2),
    ll_to_earth(lat::float, lng::float)
  ) / 1852 as nm_away
from ports_with_centroid
where lat is not null and lng is not null
order by nm_away asc
limit 10;
```

## Operational notes [#operational-notes]

* Per-vessel errors (resolution failure, insert failure) are caught individually and logged. The run bails after 10 errors to avoid log floods.
* Every run writes one row to `ingestion_logs` with `source = 'compute_route_forecasts'`. `status = 'partial'` indicates per-vessel errors; `status = 'failed'` indicates a fatal error before any vessels were processed.
* The hourly cron job is registered as `compute-route-forecasts-hourly`. Re-running the migration upserts the schedule by name and is safe.


# Temporal edge materialization (/overwatch/methodology/temporal-edges)



Axiom Overwatch maintains `temporal_edges` — a relationship graph that records every observed change in a vessel's identity over time. Each edge captures a transition between two snapshots of the same IMO (a name change, a flag change, an MMSI change) with a confidence score and an obfuscation flag. Downstream motif detectors (`detect-temporal-motifs`) traverse this graph to surface shell-hop chains, jurisdiction-shopping patterns, and other multi-step deception signals that a single-event API cannot see.

## When to use it [#when-to-use-it]

Reach for temporal edges when you need the history of how a vessel's identity has moved, not just the latest snapshot. Typical use cases:

* Tracing a renamed-and-reflagged vessel across multiple identity hops
* Distinguishing a routine rename (high name similarity) from a shell-hop (low similarity)
* Surfacing MMSI changes, which are inherently suspicious because MMSI should be stable for the life of a hull
* Feeding a motif detector that scans for repeated identity churn within a configurable window

If you only need the most recent identity change for a single vessel, query the [Risk identity API](/overwatch/api/risk) instead — it reads the underlying `vessel_identity_history` directly without the edge transform.

## How edges are built [#how-edges-are-built]

For every IMO with new history since the last run, Overwatch fetches the full snapshot history, sorts it by `observed_at`, and walks consecutive pairs. Each detected change emits one edge.




  
    ### Group history by IMO [#group-history-by-imo]

    All rows in `vessel_identity_history` for the affected IMOs are loaded and partitioned by `imo_number`. Spurious IMOs (`0`, `1`) are filtered out at this stage.
  

  
    ### Walk consecutive snapshots [#walk-consecutive-snapshots]

    Within each IMO group, snapshots are sorted by `observed_at`. The producer iterates pairwise (`prev → curr`) and tests three fields independently: `name`, `flag`, `mmsi`.
  

  
    ### Emit one edge per changed field [#emit-one-edge-per-changed-field]

    A pair can produce zero, one, two, or three edges — a snapshot where the vessel renamed, reflagged, and changed MMSI on the same day produces all three. Each edge carries its own relation type, confidence, and obfuscation flag.
  

  
    ### Upsert with deterministic IDs [#upsert-with-deterministic-ids]

    Edge IDs encode the type, IMO, and millisecond timestamps of both endpoints (`edge_{type}_{imo}_{from_ms}_{to_ms}`). Re-running over the same window is idempotent — existing rows are skipped on conflict.
  


## Relation types [#relation-types]

| Relation               | Trigger                                    | Confidence                              | Obfuscation flag |
| ---------------------- | ------------------------------------------ | --------------------------------------- | ---------------- |
| `renamed_to`           | Name changed and Jaccard similarity ≥ 0.3  | Equal to the similarity score (min 0.1) | `false`          |
| `shell_hop`            | Name changed and Jaccard similarity \< 0.3 | Equal to the similarity score (min 0.1) | `true`           |
| `jurisdiction_changed` | Flag changed                               | `0.9`                                   | `false`          |
| `mmsi_changed`         | MMSI changed                               | `0.7`                                   | `true`           |

The `renamed_to` / `shell_hop` split runs the same Jaccard character-set similarity used by `TemporalGraphEngine` in `@axiom/core`, so the live producer and the engine agree on whether a rename looks legitimate. A near-identical name (`MV ATLAS` → `M/V ATLAS`) scores high and stays as `renamed_to`; an unrelated name (`MV ATLAS` → `OCEAN STAR VII`) scores low and is promoted to `shell_hop` with `obfuscation_flag = true`.

MMSI changes are always flagged as obfuscation because MMSI is meant to be stable for the operational life of the hull. Flag changes are not — vessels legitimately reflag for tax, registry, or charter reasons — so `jurisdiction_changed` ships with the obfuscation flag clear and lets downstream motif detectors decide based on cadence and combination.

## Output shape [#output-shape]

Each edge upserted into `temporal_edges`:

* `id` — `edge_{type}_{imo}_{from_ms}_{to_ms}`, deterministic and stable
* `source_entity_id`, `target_entity_id` — `imo_{imo}_{ms}` for the two endpoints
* `relation_type` — one of the four values in the table above
* `valid_from` — the `observed_at` of the new snapshot (when the change was first observed)
* `valid_to` — `null` (open-ended; closed implicitly by the next edge from the same source)
* `confidence_decay` — name-derived for renames, fixed for flag and MMSI changes
* `obfuscation_flag` — `true` for `shell_hop` and `mmsi_changed`
* `source_feed`, `source_system`, `source_uri`, `record_id` — provenance tags identifying the producer and the underlying history row

## Production pipeline [#production-pipeline]

The producer runs as the `populate-temporal-edges` Edge Function rather than ad-hoc. It is the only writer of `temporal_edges` and is the upstream dependency for any motif-level analysis.

### Incremental schedule [#incremental-schedule]

The function runs every 4 hours under pg\_cron. Each run reads the last successful run's `metadata.last_run_at` from `ingestion_logs`, queries `vessel_identity_history` for IMOs with new observations since that timestamp, and processes only those IMOs. On the first run (or after a wipe), the function falls back to a 180-day lookback so a fresh deployment populates promptly without scanning the entire history.

To stay inside the 150-second Edge Function timeout, each run caps at 300 IMOs. History fetches are chunked at 75 IMOs per `IN()` call with a 5,000-row safety cap, which prevents PostgREST's default page limit from silently dropping rows for IMOs late in the result set. Edge upserts are batched at 500 rows.

### Direct invocation [#direct-invocation]

You can call the Edge Function directly to force an incremental pass — for example, after correcting upstream identity data:

```bash
curl -X POST "$SUPABASE_URL/functions/v1/populate-temporal-edges" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json"
```

The response includes counts for the run:

```json
{
  "edges_created": 184,
  "imos_processed": 47
}
```

Each run also writes a row to `ingestion_logs` with `source = 'populate-temporal-edges'`, the records-fetched and records-stored counts, and the `last_run_at` watermark used by the next incremental run.

### Reference remediation runner [#reference-remediation-runner]

When the [status page](/overwatch/status-page) flags `temporal_edges` as stale — typically because the cron job missed a run or hit a transient error — invoke the reference remediation runner to re-trigger the producer and let the freshness gap clear on its own.

The runner follows a strict **read → confirm → act → exit** contract: it reads the open `freshness` gap from `cockpit_gaps`, confirms remediation is actually warranted, posts to the Edge Function, and exits. It does **not** write to `cockpit_gaps` directly — `cockpit_detect_gaps` (every 15 minutes) prunes the gap on its next run once the underlying table is fresh again.

```bash
# Default — gated on an open cockpit_gaps freshness entry for temporal_edges
node scripts/remediate/populate-temporal-edges.mjs

# Plan-only — confirm a gap exists, print it, and exit without invoking
node scripts/remediate/populate-temporal-edges.mjs --dry-run

# Skip the gap gate — invoke the Edge Function unconditionally
node scripts/remediate/populate-temporal-edges.mjs --force
```

The runner requires `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` in the environment (or `--supabase-url` / `--service-key` flags). Exit codes:

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | No open gap (table fresh) **or** remediation succeeded |
| `1`  | Environment / configuration error                      |
| `2`  | Edge Function returned a non-2xx response              |

This pattern — a single source of truth (`cockpit_gaps`), runners that act but never mutate the gap table, and a detector that prunes on the next sweep — keeps `cockpit_gaps` durably consistent across multiple remediation runners without any cross-runner locking.

## What the producer doesn't do [#what-the-producer-doesnt-do]

* **No retroactive edits.** Edges are immutable once written. If `vessel_identity_history` is corrected, run a targeted backfill — re-running the function will skip existing IDs because of `ignoreDuplicates: true`.
* **No cross-IMO inference.** A renamed-and-reflagged vessel that surfaces under a new IMO is not stitched here. Cross-IMO entity resolution lives upstream in the identity-tracking pipeline.
* **No motif-level scoring.** The producer only emits the building blocks. Multi-hop patterns (rapid name churn, repeated jurisdiction flips, name + MMSI co-changes) are scored by `detect-temporal-motifs`, which traverses the edges this function writes.
* **No alerting.** The producer logs to `ingestion_logs` and exits. Alerts come from the consumers downstream of `temporal_edges`.

## Related references [#related-references]

* [Risk API](/overwatch/api/risk) — surfaces identity-change events and the underlying `vessel_identity_history`
* [Investigations API](/overwatch/api/investigations) — case files that pull identity history into a forensics view
* [Status page](/overwatch/status-page) — health view that surfaces the freshness gap on `temporal_edges`


# Voyage time allocation (/overwatch/methodology/voyage-time-allocation)



For every completed vessel visit, Axiom Overwatch decomposes the arrival-to-departure window into the time spent in each operational state. This answers the "where did the time actually go" question that a single `berth_hours` figure cannot.

## When to use this [#when-to-use-this]

* Quantify anchorage queues vs. berth productivity at a port
* Benchmark turnaround performance across vessels and operators
* Surface idle time inside a visit that does not map to anchor or berth
* Build congestion analytics that distinguish "waiting outside" from "alongside but slow"

If you only need aggregate berth utilization or congestion indices, the [Berth utilization](/overwatch/api/berth) and [Congestion](/overwatch/api/congestion) endpoints are the right tools. Use this dataset when you need a per-visit, per-state breakdown.

## The breakdown [#the-breakdown]

Each closed vessel visit produces one row keyed by `visit_id`:



| Field                   | Description                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| `total_hours`           | Full window from `arrived_at` to `departed_at`.                                                            |
| `approach_hours`        | Time from the `entered` event to the first `anchored`, `berthed`, or `departed` event.                     |
| `anchor_wait_hours`     | Sum of segments where the vessel was in the `anchored` state.                                              |
| `berth_hours`           | Sum of segments where the vessel was in the `berthed` state.                                               |
| `idle_other_hours`      | Residual inside the visit window not attributed above (typically pre-first-event slack).                   |
| `classification_method` | `event_segments` when anchor or berth events are present, `fallback_total` when only entry/exit are known. |
| `computed_at`           | Timestamp the row was written.                                                                             |

`approach_hours + anchor_wait_hours + berth_hours + idle_other_hours` reconciles to `total_hours` (within rounding).

## How it's computed [#how-its-computed]

The classifier walks `port_events` between `arrived_at` and `departed_at` and attributes the inter-event delta to the **earlier** event's state. A vessel that is `anchored` at 02:00 and `berthed` at 10:00 contributes 8 hours to `anchor_wait_hours`.

When a visit has neither an `anchored` nor a `berthed` event — usually old or sparse data — the entire window is booked to `approach_hours` and `classification_method` is set to `fallback_total`. Filter on this column when you need only fully-classified visits.

The TypeScript classifier runs on every departure close, so live visits get an allocation row as soon as the visit closes. Historical visits without a row are filled in by a SQL-side backfill (see below).


  Canal transit time is currently bucketed into `approach_hours`. A dedicated `canal_hours` column is planned once canal polygons are wired into the event stream.


## Querying [#querying]

The data lives in the `vessel_visit_time_allocation` table, indexed for `(port_id, departed_at DESC)` and `(imo_number, departed_at DESC)`.

```sql
-- Average berth vs anchor wait at a port over the last 90 days,
-- excluding visits that lacked enough events to classify.
select
  date_trunc('week', departed_at) as week,
  round(avg(approach_hours)::numeric, 2)   as avg_approach_h,
  round(avg(anchor_wait_hours)::numeric, 2) as avg_anchor_h,
  round(avg(berth_hours)::numeric, 2)       as avg_berth_h,
  round(avg(idle_other_hours)::numeric, 2)  as avg_idle_h,
  count(*)                                  as visits
from vessel_visit_time_allocation
where port_id = $1
  and departed_at >= now() - interval '90 days'
  and classification_method = 'event_segments'
group by 1
order by 1 desc;
```

```sql
-- Per-vessel turnaround at a single port.
select v.name, v.imo_number, vva.*
from vessel_visit_time_allocation vva
join vessels v on v.imo_number = vva.imo_number
where vva.port_id = $1
order by vva.departed_at desc
limit 50;
```

## Backfilling historical visits [#backfilling-historical-visits]

Visits that closed before this feature shipped do not have allocation rows. The `backfill_visit_time_allocation(p_limit)` RPC processes a bounded batch of unclassified `departed` visits using the same segmentation logic as the live writer. It is idempotent — existing rows are not overwritten.

```sql
-- One-shot top-up. Default p_limit is 500.
select backfill_visit_time_allocation();

-- Larger batch, callable by service-role contexts.
select backfill_visit_time_allocation(5000);
```

Returns the integer count of visits processed. Schedule it as a periodic top-up if you do not want to wait for the next live departure to populate a given port.

## Field reconciliation [#field-reconciliation]

If you previously joined `vessel_visits.berth_hours` for productivity dashboards, that column still exists and is unchanged. The allocation table is a sibling, not a replacement — `vessel_visits` stays narrow. Joining on `visit_id` gives you both views in one query:

```sql
select vv.id, vv.port_id, vv.berth_hours, vva.anchor_wait_hours, vva.approach_hours, vva.idle_other_hours
from vessel_visits vv
join vessel_visit_time_allocation vva on vva.visit_id = vv.id
where vv.port_id = $1 and vv.status = 'departed'
order by vv.departed_at desc;
```


# Admin API (/routeshift/api/admin)



The admin API is a separate, operator-facing surface at `https://api.routeshift.io/admin`. It never accepts a virtual `sk-proxy-…` key.

## Authentication [#authentication]

```http
Authorization: Bearer 
```

Admin credentials are provisioned in the RouteShift deployment:

* The unrestricted operator credential can call admin reads and mutations.
* Deployment-configured scoped tokens can call only an allowlist of `GET` endpoints and only for an allowed `team_id`.
* Scoped tokens cannot call admin mutations, even when a matching `team_id` is present.


  Do not expose an operator admin credential to a client application. Customer traffic belongs on the [OpenAI-compatible client API](/routeshift/api/overview) with a virtual key.


## Keys [#keys]

### Mint a virtual key [#mint-a-virtual-key]

```http
POST /admin/keys
Content-Type: application/json
{
  "alias": "prod-agent",
  "allowed_models": ["gpt-4o", "gpt-4o-mini"],
  "expires_at": "2026-12-31T00:00:00Z",
  "rpm": 60,
  "tpm": 200000,
  "monthly_budget_usd": 100,
  "metadata": { "env": "prod", "owner": "agent-team" }
}
```

This mutation requires the unrestricted operator credential. The response includes the one-time `sk-proxy-…` token. RouteShift stores only its hash; the plaintext is unrecoverable after this response.

### List keys [#list-keys]

```http
GET /admin/keys
```

With the unrestricted credential, returns key metadata without the secret. A deployment-configured scoped token can use this read only with an allowed `team_id`.

### Revoke a key [#revoke-a-key]

```http
DELETE /admin/keys/{key_id}
```

This mutation requires the unrestricted operator credential. Revocation is immediate. In-flight requests finish; new requests return `401`.

## Usage [#usage]

### Window query [#window-query]

```http
GET /admin/sessions/window?from=2026-04-01T00:00:00Z&to=2026-04-07T23:59:59Z&limit=500&cursor=…
```

This proxy endpoint requires `Authorization: Bearer `; the scoped-token allowlist does not include this route. It returns a paginated read of `session_metrics`; each row contains session ID, team ID, edit/retry turns, one-shot rate, primary model, total cost, and first/last request timestamps. The window cannot exceed seven days.

This endpoint exists primarily to feed the Layer-side yield correlation worker — see [Axiom Layer's AI usage tracking](/layer/ai-usage-tracking).

The response is `{ sessions, next_cursor }`; `limit` defaults to 200 and is capped at 1,000.

The dashboard's one-shot summary is a separate app route, not an admin-proxy endpoint:

```http
GET /api/usage/one-shot?period=24h
```

Call it on the dashboard origin with a signed-in team member session. It accepts `24h`, `7d` (default), or `30d` and returns `summary` plus `by_model`; it does not accept `model`, `from`, or `to` parameters and does not use the proxy admin token.

## SSO device flow [#sso-device-flow]

Endpoints for the native SSO device-flow key issuance ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) — see [SSO device flow](/routeshift/sso-device-flow) for the end-to-end story.

### Register an IdP connection [#register-an-idp-connection]

```http
POST /admin/idp-configs
Content-Type: application/json
{
  "team_id": "team_…",
  "provider": "okta",
  "login_domain": "acme.com",
  "issuer": "https://acme.okta.com",
  "client_id": "0oab…",
  "client_secret": "…"
}
```

Creates one connection for a `(team_id, login_domain)` pair. `provider` is `google_workspace` or `okta`. RouteShift validates the issuer's OIDC discovery document at create time and encrypts `client_secret` at rest.

Errors:

* `400` — invalid `provider`, malformed `login_domain`, non-`https://` issuer, or unreachable discovery document.
* `403` — `SSO_DEVICE_FLOW_ENABLED` is not set to `true` on the deployment.
* `409` — the `login_domain` is already registered to another team.

### Update an IdP connection [#update-an-idp-connection]

```http
PATCH /admin/idp-configs/{id}?team_id=team_…
Content-Type: application/json
{
  "issuer": "https://acme.okta.com",
  "client_id": "0oab…",
  "client_secret": "…"
}
```

Any subset of `issuer`, `client_id`, `client_secret` can be updated. `login_domain` and `provider` are immutable — delete and re-create to change them.

### Delete an IdP connection [#delete-an-idp-connection]

```http
DELETE /admin/idp-configs/{id}?team_id=team_…
```

Removes the connection. In-flight device authorizations that reference it are cascaded and start failing on their next poll. Existing SSO-issued keys are **not** revoked — revoke them separately via `DELETE /admin/keys/{key_id}` if needed.

## Device flow (RFC 8628) [#device-flow-rfc-8628]

Public endpoints called by CLIs and browsers, not with an admin token. Rate limiting and an enabled, provisioned identity-provider connection still apply; the presence of these routes does not guarantee device login is configured for a team.

### Start a device authorization [#start-a-device-authorization]

```http
POST /oauth/device/code
Content-Type: application/json
{ "email": "employee@acme.com" }
```

Response:

```json
{
  "device_code": "…",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://api.routeshift.io/oauth/device/verify",
  "verification_uri_complete": "https://api.routeshift.io/oauth/device/verify?user_code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}
```

### Poll for the key [#poll-for-the-key]

```http
POST /oauth/device/token
Content-Type: application/json
{
  "device_code": "…",
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
}
```

Returns `{ "access_token": "sk-proxy-…", "token_type": "Bearer", "expires_in": 28800 }` once approved. Before approval, returns `authorization_pending`, `slow_down`, `access_denied`, `expired_token`, or `invalid_grant` per RFC 8628.

### Browser-facing endpoints [#browser-facing-endpoints]

* `GET /oauth/device/verify` — HTML page where a signed-in employee approves or denies a pending authorization.
* `POST /oauth/device/verify` — same-origin JSON submission from the verify page. `Content-Type` must be `application/json`.
* `GET /oauth/device/callback` — OIDC redirect target. Register `${SSO_CALLBACK_BASE_URL}/oauth/device/callback` in each IdP's app console.

## Routing [#routing]

### Invalidate alias cache [#invalidate-alias-cache]

```http
POST /admin/model-aliases/invalidate
```

Tells the proxy fleet to drop its in-memory model-alias cache. Issued automatically when you save an alias from the dashboard, but exposed here for tooling that edits aliases out-of-band.

### Invalidate preset cache [#invalidate-preset-cache]

```http
POST /admin/presets/invalidate
Content-Type: application/json

{ "team_id": "team_01H…" }
```

Tells the proxy fleet to drop its in-memory copy of one team's presets so the next request resolves the new body immediately. The dashboard calls this automatically after every preset create, publish, delete, or disable — see [Presets → Proxy cache invalidation](/routeshift/presets#proxy-cache-invalidation) for how the dashboard surfaces success and failure to API callers.

A non-OK response or network failure does **not** roll back the database write on the dashboard side; the caller receives `proxy_cache_invalidated: false` and the proxy re-reads the preset when its per-team TTL (60 seconds) expires.

## Response shapes [#response-shapes]

Success responses are endpoint-specific. Authentication and authorization errors use an error object such as:

```json
{
  "error": {
    "message": "Unauthorized"
  }
}
```


# Chat completions (/routeshift/api/chat-completions)



The chat-completions endpoint is a drop-in replacement for `https://api.openai.com/v1/chat/completions`. The wire format is identical; the routing, logging, and cost accounting happens server-side.

## Endpoint [#endpoint]

```http
POST https://api.routeshift.io/v1/chat/completions
Authorization: Bearer sk-proxy-…
Content-Type: application/json
```

## Request body [#request-body]

Standard OpenAI shape — `model`, `messages`, `temperature`, `max_tokens`, `stream`, `tools`, etc. RouteShift adds two optional extension fields under `metadata`:

| Field                 | Type   | Effect                                                                                                                     |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `metadata.route_hint` | string | Overrides the rule chain and pins this request to the named alias.                                                         |
| `metadata.session_id` | string | Forces session stitching to use this ID instead of inferring one. Useful when you already have a conversation ID upstream. |

Anything else under `metadata` is preserved into `request_logs.metadata` for downstream analytics.

Requests can also opt in to the [web search plugin](/routeshift/web-search) by appending `:online` to the model name or adding a `web` entry to a top-level `plugins` array — RouteShift resolves the plugin, injects labeled search context into the system prompt, and forwards a clean payload upstream.

## Streaming [#streaming]

Set `"stream": true` to receive Server-Sent Events. The format matches OpenAI's `data: { ... }\n\n` chunks. RouteShift relays chunks as they arrive from upstream — no extra buffering — and writes the request log when the stream closes.

## Examples [#examples]


  
    
      cURL
    

    
      TypeScript SDK
    

    
      OpenAI Python (drop-in)
    
  

  
    ```bash
    curl https://api.routeshift.io/v1/chat/completions \
      -H "Authorization: Bearer sk-proxy-…" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-4o-mini",
        "messages": [
          {"role": "system", "content": "You are concise."},
          {"role": "user", "content": "What is 2 + 2?"}
        ]
      }'
    ```
  

  
    ```ts
    import { ProxyClient } from "@routeshift/sdk";

    const client = new ProxyClient({
      baseUrl: "https://api.routeshift.io",
      apiKey: process.env.ROUTESHIFT_KEY!,
    });

    const res = await client.chat({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: "What is 2 + 2?" }],
    });

    console.log(res.choices[0].message.content);
    ```
  

  
    ```py
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.routeshift.io/v1",
        api_key="sk-proxy-…",
    )

    res = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "What is 2 + 2?"}],
    )
    print(res.choices[0].message.content)
    ```
  


## Response headers [#response-headers]

Beyond the standard OpenAI response, RouteShift adds:

* `X-RouteShift-Resolved-Model` — the upstream model that actually served the request (after aliases and rule chain).
* `X-RouteShift-Provider` — provider name.
* `X-RouteShift-Cost-Microcents` — actual cost in microcents.
* `X-RouteShift-Session-Id` — session ID this request was stitched into.

These mirror the values written to `request_logs` so you can correlate client-side observability with the dashboard.


# API overview (/routeshift/api/overview)



RouteShift exposes an OpenAI-compatible client surface at:

```text
https://api.routeshift.io/v1
```

Use a RouteShift virtual key in the standard bearer-token header:

```http
Authorization: Bearer sk-proxy-…
```

## Supported client endpoints [#supported-client-endpoints]

| Method | Path                   | Use for                                                                              |
| ------ | ---------------------- | ------------------------------------------------------------------------------------ |
| `POST` | `/v1/chat/completions` | Send non-streaming or streaming chat-completion requests through your routing rules. |
| `POST` | `/v1/embeddings`       | Create embeddings through a configured upstream provider.                            |
| `GET`  | `/v1/models`           | List the models currently exposed by RouteShift.                                     |
| `GET`  | `/v1/models/{model}`   | Read one model's public metadata.                                                    |


  Anthropic can be configured as an upstream provider, but RouteShift does not currently expose a public Anthropic Messages-compatible endpoint. Send client traffic through the OpenAI-compatible routes above.


## Virtual keys [#virtual-keys]

Virtual keys use the `sk-proxy-…` prefix and authenticate client traffic. Each key can carry its own model allowlist, requests-per-minute and tokens-per-minute limits, budget, expiry, and metadata.

RouteShift returns a key's plaintext value only when the key is created. Store it in an approved secret manager and rotate it if it is exposed.

## First request [#first-request]

```bash
curl https://api.routeshift.io/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Summarize this request in one sentence." }
    ]
  }'
```

Continue with [Chat completions](/routeshift/api/chat-completions) for request and streaming examples.

## Rate limits [#rate-limits]

Each virtual key carries its own RPM and TPM caps. See [Virtual API keys](/routeshift/keys). When a cap is hit, RouteShift returns `429` and identifies the proxy-side reason.

```http
HTTP/1.1 429 Too Many Requests
X-RouteShift-Reason: rpm_exceeded
Retry-After: 7
```

`Retry-After` is in seconds.

## Errors [#errors]

RouteShift preserves the upstream provider's error format when possible. Proxy-side errors use `X-RouteShift-Reason` so you can distinguish a RouteShift policy decision from an upstream failure.

| Reason                  | Status | Meaning                                                       |
| ----------------------- | ------ | ------------------------------------------------------------- |
| `key_revoked`           | 401    | Virtual key was revoked.                                      |
| `key_expired`           | 401    | Virtual key passed its expiry.                                |
| `model_not_allowed`     | 403    | Model is not in this key's allowlist.                         |
| `rpm_exceeded`          | 429    | Per-key requests-per-minute cap was reached.                  |
| `tpm_exceeded`          | 429    | Per-key tokens-per-minute cap was reached.                    |
| `budget_exceeded`       | 429    | Monthly budget was reached.                                   |
| `cost_ceiling_exceeded` | 429    | Per-request cost ceiling was reached during a fallback chain. |
| `no_provider_key`       | 503    | No configured provider key can serve the resolved upstream.   |
| `upstream_cooldown`     | 503    | All eligible credentials for the provider are cooling down.   |

## Operator admin surface [#operator-admin-surface]

RouteShift also has an operator-facing `/admin` surface for key lifecycle, usage, routing configuration, and cache invalidation. It does not accept virtual keys and is not a second client compatibility API.

Admin credentials and endpoint scope are deployment-managed. Scoped admin tokens are limited to specific read endpoints and explicit team IDs; mutation endpoints require the unrestricted operator credential. See the [Admin API](/routeshift/api/admin) before building an internal integration.