API
Platform administration
Organizations, plans, regions and locations, for platform administrators.
These routes check scopes in the platform organization, not in an organization in the path.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/platform/analytics | Traffic across every customer deployment, with the busiest organizations. |
GET /v1/platform/mail/usage | Mail sent and received per organization over the last days. |
GET /v1/platform/usage | Cost per organization for a month (month=YYYY-MM, default this month) from Cost Explorer, grouped by the si:org cost allocation tag, with each organization's Serverless App Services, repositories, databases and buckets, deployment requests and bytes, and mail sent and received in the month. Spend without the tag is untagged. |
POST /v1/platform/coverage/runs | Records a test coverage run of the platform's repository: its commit, branch, pipeline run and each workspace's tests, line, branch and function coverage, least covered and untested files. Totals are worked out from the workspaces. Kept 90 days. Needs platform:coverage (the nightly pipeline's key). |
GET /v1/platform/coverage/latest | The latest coverage run's id, commit and start, so a pipeline can skip a commit it already reported. Needs platform:coverage or platform:admin. |
GET /v1/platform/coverage | Coverage runs of the last 90 days (newest first) with their totals, a run's workspaces (run=, default the latest) and the workspaces of the run before it, for changes. |
GET /v1/platform/coverage/runs/:runId/package | One workspace of a coverage run (dir=services/api) with its least covered loaded files and the source files no test loaded. |
GET /v1/platform/mirage/social/settings | Mirage's social limits, ranking weights and blocked words: what's stored, the settings in force, the defaults and each number's range (bounds). Platform staff (platform:admin). |
PUT /v1/platform/mirage/social/settings | Changes social settings (any of postLength, mediaPerPost, imageBytes, videoBytes, editWindowMinutes, editsPerPost, postsPerHour, followsPerDay, maxFollowing, fanoutMaxFollowers, fanoutBatch, feedDays, storyHours, notificationDays, ranking, blockedWords; null restores a default; ranking merges weight by weight). Applies within a minute. Audited. Platform staff. |
PUT /v1/platform/mirage/social/age/:userId | Records an age check by hand (appeals, testing): outcome 16_plus or under_16 and an optional note. Under 16 deactivates their Feed (hidden from everyone, kept) until a later check says 16 or over. Audited. Platform staff. |
DELETE /v1/platform/mirage/social/posts/:postId | Removes a post (reason: one of the report reasons, or a few words); its author is told why. Audited. Platform staff. |
GET /v1/platform/mirage/competition/circuits | Every closed circuit on the leaderboards' list, enabled or not, with its boundary, start/finish line and length. Platform staff. |
PUT /v1/platform/mirage/competition/circuits/:circuitId | Adds or changes a circuit: name, region, boundary ([lat, lon] points around the track and no public road), gate (the start/finish line, two points), lengthKm, verified, enabled (only once verified), optional notes. Audited. Platform staff. |
DELETE /v1/platform/mirage/competition/circuits/:circuitId | Deletes a circuit. Audited. Platform staff. |
GET /v1/platform/mirage/competition/factors | The factors behind leaderboards' CO₂, charging shares and smoothness: a petrol car's grams per km, the grid's grams per kWh, off-peak and solar hours, and the smoothness thresholds. Platform staff. |
PUT /v1/platform/mirage/competition/factors | Changes the factors (all of them). Audited. Platform staff. |
GET /v1/platform/mirage/gifs | Mirage's GIF settings: the provider (klipy, giphy or off) and content rating in force, the defaults, and which providers have their key (never the key). Platform staff (platform:admin). |
PUT /v1/platform/mirage/gifs | Changes the GIF provider or content rating (g, pg, pg-13, r). Applies within a minute. Audited. Platform staff. |
GET /v1/platform/age/settings | The age gate's settings: mode (off, self_declared: the date of birth, estimation: a face check in ID) and the face check's rules (region, minConfidence, passLowAtLeast, underHighBelow, retries, attemptsPerDay): what's stored, what's in force, the defaults and who changed them last. Platform staff. |
PUT /v1/platform/age/settings | Changes the age gate's mode or the face check's rules (estimation, any of them; null puts one back to its default). Takes effect within a minute. Audited with the mode. Platform staff. |
GET /v1/platform/age/accounts | An account's age by email: its date of birth (and whether staff set it), the age it gives or its last check's, the gate and face checks left today. 404 when nobody has the address. Platform staff. |
PUT /v1/platform/age/accounts/:userId/date-of-birth | Corrects someone's date of birth (dateOfBirth, YYYY-MM-DD; an optional note), with their evidence. The correction becomes the account's age: earlier checks and face-check counts go. Audited with the note (what staff saw), never the date. Platform staff. |
DELETE /v1/platform/age/accounts/:userId | Clears someone's age (date of birth, checks and face-check counts), so they declare again. Audited. Platform staff. |
GET /v1/platform/caity | The assistant's platform settings: search (the web search provider, exa, brave or mock, any prices per 1,000 queries, the defaultPrices, and which providers have their key on this stage, never the key) voice (whether speech to speech is on, sonic, and whether this stage runs the voice bridge) and images (whether pictures are on, and each image model with its name, where it runs, what it does, price per picture and whether it's enabled), each with when it changed. Platform staff. |
PUT /v1/platform/caity/search | Changes the web search provider (exa, brave or mock) and, optionally, prices ({ links, text } US$ per 1,000 queries per provider; null drops them). A provider without its key answers from the mock. Applies within a minute. Audited. Platform staff. |
PUT /v1/platform/caity/voice | Turns the assistant's speech to speech on or off (sonic). It runs only where the stage runs the voice bridge. Applies within 30 seconds. Audited. Platform staff. |
PUT /v1/platform/caity/images | Turns the assistant's pictures on or off (on) and changes image models by id (models: { <id>: { enabled, pricePerImage } }, US$0 to US$10 a picture); what it leaves out keeps its value. Applies within 30 seconds. Audited. Platform staff. |
PUT /v1/platform/caity/code-cloud | Changes Code mode in the cloud: on or off (on), the package registries its builds may reach (registries, host names or *. and a domain, at most 60), the agent release each platform runs (agent: { "linux-arm64": { version, sha256 } }, null removes one) and a build minute's price (minuteUsd). What it leaves out stays. Applies within 30 seconds. Audited. Platform staff. |
GET /v1/platform/health/metrics | Every Health metric definition (enabled or not): category, kind, units, aggregation, sensitivity, HealthKit mapping and leaderboard mode. |
PUT /v1/platform/health/metrics/:metricId | Adds or changes a metric definition. In the platform's audit log. |
PUT /v1/platform/health/metrics/:metricId/enabled | Turns a metric on or off (enabled); definitions are never deleted. In the platform's audit log. |
POST /v1/platform/health/metrics/seed | Adds seed definitions the registry is missing (never changes existing ones). |
GET /v1/platform/health/settings | Health's platform settings (samples per request, how long the audit keeps entries) and their defaults. |
PUT /v1/platform/health/settings | Changes Health's platform settings. In the platform's audit log. |
GET /v1/platform/health/restricted-leaderboards | The Mirage servers allowed leaderboards for restricted metrics, with their names. Platform staff. |
PUT /v1/platform/health/restricted-leaderboards/:serverId | Allows a Mirage server leaderboards for restricted metrics: its managers then see the option. In the platform's audit log. |
DELETE /v1/platform/health/restricted-leaderboards/:serverId | Takes the allowance away: the option goes off and everyone ranked on those boards there is taken off at once (removed: opt-ins and scores). In the platform's audit log. |
GET /v1/platform/food/receipt-rules | The supermarkets whose e-receipts Food reads (stores, enabled or not, in order: sender domains, receipt words, end-of-items and not-item lines, house brands, how their PDFs are read (pdf: rules, model or off)), the words that mark a receipt line as not food (nonFoodWords), and which kinds are still the seed (seed). Platform staff only. |
PUT /v1/platform/food/receipt-stores/:storeId | Creates or replaces a receipt store. Sender domains must be the store's own (public suffixes and free mail are refused). Mail and Food use it within a minute. Audited. |
DELETE /v1/platform/food/receipt-stores/:storeId | Removes a receipt store. With none left, the seed's stores are read again; turn a store off to read none. Audited. |
POST /v1/platform/food/non-food-words | Adds a non-food word (word, stored lower case). Audited. |
DELETE /v1/platform/food/non-food-words/:word | Removes a non-food word. Audited. |
POST /v1/platform/food/receipt-rules/test | Reads a pasted e-receipt (from, subject, body as HTML or text), a PDF receipt (pdf, base64, up to 110 KB) or both with the saved rules, as Food does without the model: the store, whether it's a receipt, where the lines came from, what became of the PDF (its text, or why it wasn't read), the date, the total and each line, food or not. Nothing is kept. |
GET /v1/platform/free-mail-domains | The free mail domains no organisation can verify (domains, sorted), and seed: true while the stage has none saved and reads the built-in list. |
POST /v1/platform/free-mail-domains | Adds a free mail domain (domain, stored lower case in ASCII). An organisation that verified exactly that domain loses it at once (released); subdomains at their next check. Audited. |
DELETE /v1/platform/free-mail-domains/:domain | Removes a free mail domain. Audited. |
GET /v1/platform/integration-apps | The platform's app at each provider: client id, scopes, whether it's on and ready, and the redirect URL to register. Secrets only as their last four characters. Platform admins. |
PUT /v1/platform/integration-apps/:provider | Saves a provider's app: client id, client and signing secrets (sealed; null clears), scopes (null for the defaults), on or off. Turning it on needs the whole registration. A platform owner. |
GET /v1/platform/integration-apps/:provider | One provider's app, as the list gives it. Platform admins. |
GET /v1/platform/profile-effects | Every profile effect in the catalogue (enabled or not): id, name, renderer (sparkles, snow, hearts, glow, aurora or confetti), colors and order. |
PUT /v1/platform/profile-effects/:effectId | Adds or changes a profile effect (name, renderer, one to four colors, enabled, sortOrder). People wearing it keep the look they chose until they choose again. In the platform's audit log. |
PUT /v1/platform/profile-effects/:effectId/enabled | Turns a profile effect on or off (enabled): off, nobody can choose it. In the platform's audit log. |
POST /v1/platform/profile-effects/seed | Adds the built-in profile effects the catalogue is missing (never changes existing ones). |
GET /v1/platform/locales | The languages people can choose, as data (locales: locale, label, spelling (au or us), weekStart (0 Sunday … 6 Saturday), enabled, sortOrder), whether a list is stored or the built-in one applies, the built-in one, and who changed it last. Platform staff. |
PUT /v1/platform/locales | Replaces the list of languages (locales: the whole list; null goes back to the built-in English (Australia) and English (US)). en-AU stays enabled; each language once. People's apps see the change within a minute. In the platform's audit log. |
GET /v1/platform/festive | Festive themes' yearly periods, as data (periods, in priority order: id, name, when (fixed start and end MM-DD, easter or newMoon day offsets), themes, defaultTheme, regions, enabled), the themes the platform draws (themes), whether a list is stored or the built-in one applies, the built-in one, and who changed it last. Platform staff. |
PUT /v1/platform/festive | Replaces festive themes' periods (periods: the whole list, in priority order; null goes back to the built-in list). Each period's themes must be ones the platform draws, its default one of them, and it runs at most four months. Apps follow within eleven minutes. In the platform's audit log. |
GET /v1/platform/badges | The settings, the seed (to reset to) and who saved them last. |
PUT /v1/platform/badges | Saves the tiers, the cutoff (YYYY-MM-DD) and the lapse allowed in days. |
GET /v1/platform/badges/people/:who | One person (usr_… or their email): their badges, whether they show them, staff's grant and the accounts that count. |
PUT /v1/platform/badges/people/:who/early-supporter | Early Supporter by hand: granted, revoked, or auto (billing decides again). |
GET /v1/platform/people/subsidised | Everyone the platform pays a personal plan for, newest first (an ended one until the reconcile removes it). |
GET /v1/platform/people/:who | One person (usr_… or their email): the plan they have, a subsidy and their own subscription. |
PUT /v1/platform/people/:who/subsidy | Gives the person a personal plan the platform pays for, or changes its plan, end (until, ms; null: no end) or note (null clears it). No card and no subscription; one they pay for keeps running and they get the higher of the two. |
POST /v1/platform/people/:who/password-reset | "Send Password Reset" (docs/id/recovery.md): the account's own address gets a recovery link. Platform owners and admins acting themselves (never a key, Caity or an MCP client); they never see the link. Audited in the platform org. |
DELETE /v1/platform/people/:who/subsidy | Takes the subsidy away: back to their paid plan, else Free (files kept; the retention period starts). |
GET /v1/platform/mirage/reports | Every Mirage report (open ones, or status=all), newest first, with the reporter and server: the platform's review queue. before pages. platform:admin. |
PATCH /v1/platform/mirage/reports/:reportId | Marks any report actioned, dismissed or open, with an optional note. platform:admin. |
GET /v1/platform/pipelines/runners | Every hosted runner type (enabled or not): label, CodeBuild project, environment and compute type, image, minute multiplier, longest timeout, Docker, orgs it's limited to. Needs platform:admin. |
PUT /v1/platform/pipelines/runners/:label | Creates or changes a hosted runner type (Lambda compute: at most 15 minutes, no Docker). Needs platform:infra. |
DELETE /v1/platform/pipelines/runners/:label | Removes a hosted runner type; jobs naming it fail with the list of others. Needs platform:infra. |
GET /v1/platform/pipelines/settings | The platform's pipeline settings (matrix and run size, log, artifact and cache sizes, workflow file size, schedule interval, approval expiry, queue timeout, secret size and count) and their defaults. Needs platform:admin. |
PUT /v1/platform/pipelines/settings | Changes the pipeline settings; they apply within a minute. Needs platform:infra. |
GET /v1/platform/feedback | The inbox: reports newest first (open ones unless status says otherwise), filtered, with possible duplicates. |
GET /v1/platform/feedback/:reportId | One report: images (signed links), comments and possible duplicates. |
PATCH /v1/platform/feedback/:reportId | Triage: status, severity (bugs) or type. |
POST /v1/platform/feedback/:reportId/comments | An admin's comment (only admins see them). |
POST /v1/platform/feedback/:reportId/convert | Turns a report into an issue in one of the platform org's Tasks spaces (space: its key or id), with its text, context and images; the report links to the issue and is triaged. |
DELETE /v1/platform/feedback/:reportId | Deletes a report, its comments and its images. |
GET /v1/platform/deletions | Admin → Deletions: open account deletion requests by when they're due, then recent closed ones (or those with status), with the person's address until erased, the grace, where it was asked from, and in shadow mode the plan its erasure would run. platform:admin. |
GET /v1/platform/deletions/:delId | One account deletion request and each handler's task (phase, status, attempts, counts, last error code). platform:admin. |
GET /v1/platform/orgs | Platform organizations and the newest customer organizations. |
POST /v1/platform/orgs | Onboards a customer: the org (slug claimed atomically, optional plan) and an owner invite. The invite link is in the response once (and mailed where SES is set up); the owner joins through ID. |
PATCH /v1/platform/orgs/:orgId | Assigns an organization to a plan (planId; null returns it to the default plan) and/or sets whether the platform pays for it (subsidised: every app, no card). Ending a subsidy makes the organization subscribe in Tenant → Billing before its apps open again. |
GET /v1/platform/stats | Counts of organizations, customers, regions and locations. |
GET /v1/platform/audit | The platform organization's audit log: registry and plan changes, onboarding and the platform organization's own activity. |
GET /v1/platform/oauth-clients | Self-registered (MCP) clients at ID: who registered what, how many people connected, last use. |
DELETE /v1/platform/oauth-clients/:clientId | Removes a self-registered client: its approvals and refresh tokens stop working at once (the token endpoint no longer knows the client); access tokens it holds last up to an hour. |
GET /v1/platform/regions | The region and location registry. |
PUT /v1/platform/regions/:regionId | Creates or replaces a region. Services that ran from the cached registry see the change within a minute. |
PUT /v1/platform/locations/:locationId | Creates or replaces a location with its ordered region list (primary first). |
GET /v1/platform/billing/signups | Pay first (docs/billing/README.md → Pay first): the funnel for the last 30 days (checkouts started, paid, details given, onboarding complete) and the sign-ups that paid but haven't finished (the pending orgs and people), newest first. |
GET /v1/platform/billing/promotions | Promotion codes (docs/billing/promotions.md): the codes and coupons in the stage's payment provider, the subscriptions carrying a discount now, who may create codes, and whether this person may. |
POST /v1/platform/billing/promotions | Makes a code (and its coupon, unless couponId names one). Who may: billing.promotionCreators. |
PATCH /v1/platform/billing/promotions/:promotionCodeId | Turns a code off (or on again): no new redemptions; discounts already given keep running. |
DELETE /v1/platform/billing/coupons/:couponId | Deletes a coupon: none of its codes can be redeemed any more; discounts already given keep running. |
GET /v1/platform/billing/redemptions | Redemptions, newest first: one code's (?promotionCodeId=) or all. |
PUT /v1/platform/billing/promotion-creators | Who may create codes: platform roles and people. Platform owners only. |
GET /v1/platform/plans | Plans and their settings. Organizations without a plan use the default plan. |
PUT /v1/platform/plans/:planId | Creates or replaces a plan. Optional limits that aren't sent keep their stored value; null clears one (the default applies). Making a plan the default clears the flag on the others. |
GET /v1/platform/office-templates | Built-in templates of Documents, Sheets and Slides (Admin → Templates): every one, hidden ones included. |
GET /v1/platform/video-presets | Video's export presets (Admin → Templates → Video presets): every one, hidden ones included. |
PUT /v1/platform/video-presets/:presetId | Changes an export preset's label, description, settings, order or visibility, or adds one; the app sees it within a minute. |
GET /v1/platform/office-fonts | The editors' fonts (Admin → Fonts): every family, hidden ones included, and whether the stage has the files. |
PATCH /v1/platform/office-fonts/:family | Recategorises, orders or hides a font; the menus see it within a minute. |
PATCH /v1/platform/office-templates/:templateId | Renames, recategorises, orders or hides a built-in template; the galleries see it within a minute. |
GET /v1/platform/models | Chat models and the capabilities that shape their requests. Chat reads them within the cache TTL. |
PUT /v1/platform/models/:modelId | Creates or replaces a chat model in the catalog: label, whether it's enabled or the default, thinking and effort settings, output tokens and fallback model. Making a model the default clears the flag on the others. |
GET /v1/platform/flight-coverage | Areas the Maps flight poller always covers (centre, radius, label, enabled), besides watches and areas people are viewing. |
PUT /v1/platform/flight-coverage/:areaId | Creates or replaces a standing coverage area. The poller picks it up within a minute; radius is capped at the ADS-B source's maximum. |
GET /v1/platform/flight-sources | Maps: the ADS-B sources the flight poller uses, in order (seeded adsb.lol, adsb.fi, ADS-B Exchange as a capped last resort). The poller reads them within the cache TTL. |
PUT /v1/platform/flight-sources/:sourceId | Changes an ADS-B source: its place in the order, whether it's used, and its daily and monthly request budgets. |
GET /v1/platform/deploys | Maps: Admin's "SMS for Maps alerts" switch (the maps.sms row, off by default). Off, the notifications service sends no Maps alert by text or call (docs/platform/notifications.md → Maps texts); containers see a change within 30 seconds. |
GET /v1/platform/maps/sms | The SMS for Maps alerts switch (settings.on, off by default) and when and by whom it last changed. Off, no Maps alert texts or calls anyone. Platform staff only. |
PUT /v1/platform/maps/sms | Turns SMS for Maps alerts on or off (on). Applies within 30 seconds; saved text choices on watches, zones and people's settings are kept. Audited. Platform staff only. |
GET /v1/platform/incident-sources | Maps: the emergency feeds the incidents poller reads, in order (rows: the seed's until one is saved), the parsers it knows (formats) and how each feed did last (status, from the live picture). The poller reads them within the cache TTL. |
PUT /v1/platform/incident-sources/:sourceId | Adds or changes an emergency feed: label, parser (format), https URL (an ftp:// directory for the Bureau of Meteorology's format), state, order, on or off, poll interval (30–3,600 s), credit line, licence and the agency's page. The first save also writes the seed's other feeds so they stay in use. |
DELETE /v1/platform/incident-sources/:sourceId | Removes an emergency feed. Its incidents leave the map at the next poll without alerting anyone. |
GET /v1/platform/limits | Maps: aircraft presets watches target ({ kind: "preset", value: <presetId> }), e.g. police and emergency callsigns. Targets are hex, registration, callsign or type, * for prefixes. The poller reads them within the cache TTL. |
PUT /v1/platform/limits/:limitId | Sets a limit (null: back to its default). Readers see it within a minute. |
GET /v1/platform/marketing/sms-prices | What a Marketing text part costs per destination (currency, prices of prefix, country, perPart): the prices in force, the built-in ones, and whether any are stored. Platform staff (platform:admin). |
PUT /v1/platform/marketing/sms-prices | Replaces the text prices (prices; null puts the built-in ones back). Journeys' text steps show costs from them within a minute. Audited. Platform staff. |
GET /v1/platform/aircraft-presets | Aircraft presets flight watches can target ({ kind: "preset", value: <presetId> }): label, targets ({ kind: hex | registration | callsign | type, value }, * for prefixes), enabled, sortOrder. |
PUT /v1/platform/aircraft-presets/:presetId | Creates or replaces an aircraft preset (label, targets, enabled, sortOrder). Watches that use it pick it up within a minute. |
DELETE /v1/platform/aircraft-presets/:presetId | Removes an aircraft preset; watches that named it stop matching through it. |
GET /v1/platform/mail-category-rules | Rules that sort received mail into inbox categories, in order: match (domain, local, subject or header), value, category (primary, transactions, updates, promotions), enabled, sortOrder. |
POST /v1/platform/mail-category-rules/test | Classifies a pasted message with the saved rules, exactly as delivery would for a sender the mailbox doesn't know: pasted headers (or a whole message), or From and Subject. |
PUT /v1/platform/mail-category-rules/:ruleId | Creates or replaces a mail category rule. Mail received from then on (within a minute) follows it; mail already received keeps its category. |
DELETE /v1/platform/mail-category-rules/:ruleId | Removes a mail category rule. |
GET /v1/platform/mail-lends | Mail domains lent out of the shared platform zone, each with its org and how far Mail has got with it (Admin → Mail → Lent Domains; docs/mail/README.md → Lent domains). parent: the name this stage lends under. |
POST /v1/platform/mail-lends | Lends one name to one org for Mail. Never replaces a lend: take it back first. |
DELETE /v1/platform/mail-lends/:domain | Takes a lend back once its org no longer has the domain in Mail (removing it there deletes its records). |
DELETE /v1/platform/flight-coverage/:areaId | Removes a standing coverage area. |